home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 2004 #6 / Amiga Plus CD - 2004 - No. 06.iso / AmiSoft / Util / libs / ExtraLib.lha / Extra / Docs / Extra.DOC next >
Text File  |  2004-05-30  |  136KB  |  2,464 lines
  1. ExtractDocs Version 1.0
  2. Copyright © Roland Heyder 1994
  3.  
  4. TABLE OF CONTENTS
  5. ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  6. Legal-ReadMe
  7. Haftung
  8. Hinweise
  9. Details
  10. Danksagung ??
  11. extra.library / BAMCheckSum()           (OFFSET -42) V1.323
  12. extra.library / BootBlockSum()          (OFFSET -48) V1.323
  13. extra.library / DiskBlockSum()          (OFFSET -54) V1.323
  14. extra.library / OpenBuf()               (OFFSET -60) V1.323
  15. extra.library / v2_OpenBuf()            (OFFSET -300) V2.062
  16. extra.library / CloseBuf()              (OFFSET -66) V1.323
  17. extra.library / FileToBuf()             (OFFSET -72) V1.323
  18. extra.library / v2_FileToBuf()          (OFFSET -306) V2.062
  19. extra.library / BufToFile()             (OFFSET -78) V1.323
  20. extra.library / ClearBuf()              (OFFSET -84) V1.323
  21. extra.library / DuplicateBuf()          (OFFSET -90) V1.323
  22. extra.library / v2_DuplicateBuf()       (OFFSET -312) V2.062
  23. extra.library / BufInfo()               (OFFSET -96) V1.323
  24. extra.library / SeekBuf()               (OFFSET -102) V1.323
  25. extra.library / Store()                 (OFFSET -108) V1.323
  26. extra.library / InsertBuf()             (OFFSET -114) V1.323
  27. extra.library / InsertFile()            (OFFSET -120) V1.323
  28. extra.library / Replace()               (OFFSET -126) V1.323
  29. extra.library / Get()                   (OFFSET -132) V1.323
  30. extra.library / Clear()                 (OFFSET -138) V1.323
  31. extra.library / FindData()              (OFFSET -144) V1.323
  32. extra.library / FindNext()              (OFFSET -150) V1.323
  33. extra.library / FindPrev()              (OFFSET -156) V1.323
  34. extra.library / FreeFinds()             (OFFSET -162) V1.323
  35. extra.library / SetBookmark()           (OFFSET -168) V1.323
  36. extra.library / GotoBookmark()          (OFFSET -174) V1.323
  37. extra.library / FindString()            (OFFSET -180) V1.323
  38. extra.library / GetLength()             (OFFSET -186) V1.323
  39. extra.library / LastError()             (OFFSET -192) V1.323
  40. extra.library / LongToString()          (OFFSET -198) V1.323
  41. extra.library / StringToLong()          (OFFSET -204) V1.323
  42. extra.library / PackByteRun1()          (OFFSET -210) V1.323
  43. extra.library / UnpackByteRun1()        (OFFSET -216) V1.323
  44. extra.library / PrintIoError()          (OFFSET -222) V1.323
  45. extra.library / FlipCase()              (OFFSET -228) V1.323
  46. extra.library / CmpMem()                (OFFSET -234) V1.323
  47. extra.library / CopyMemI()              (OFFSET -240) V1.323
  48. extra.library / FillMem()               (OFFSET -246) V1.323
  49. extra.library / GetMem()                (OFFSET -252) V1.323
  50. extra.library / UnGetMem()              (OFFSET -258) V1.323
  51. extra.library / OutlineOff()            (OFFSET -264) V1.323
  52. extra.library / OutlineOn()             (OFFSET -270) V1.323
  53. extra.library / SetOPen()               (OFFSET -276) V1.323
  54. extra.library / SpecText()              (OFFSET -282) V1.323
  55. extra.library / SpecTextPrefs()         (OFFSET -288) V1.323
  56. extra.library / ShowMsg()               (OFFSET -294) V1.323
  57. String-Verwaltung
  58. Ausgabe-Format-String
  59. extra.library / VSPrintF()              (OFFSET -318) V3.342
  60. extra.library / GetMem16()              (OFFSET -324) V3.342
  61. extra.library / DiscardString()         (OFFSET -330) V3.342
  62. extra.library / Int32ToString()         (OFFSET -336) V3.342
  63. extra.library / Int64ToString()         (OFFSET -342) V3.342
  64. extra.library / FFPToString()           (OFFSET -348) V3.342
  65. extra.library / SGLToString()           (OFFSET -354) V3.342
  66. extra.library / DBLToString()           (OFFSET -360) V3.342
  67. extra.library / StringToInt32()         (OFFSET -366) V3.342
  68. extra.library / SMCOLOR()
  69. extra.library / SMTEXTP()
  70. extra.library / SMTEXT()
  71. lvo / Lib-Call-Macro
  72. rhosigma / C-Stubs für »extra.library« Funktionen
  73. rhosigma / GetIOReq()                      V1.286
  74. rhosigma / CopyIOReq()                     V1.286
  75. rhosigma / FreeIOReq()                     V1.286
  76. rhosigma / DoCMD()                         V1.286
  77. rhosigma / SendCMD()                       V1.286
  78. rhosigma / WaitCMD()                       V1.286
  79.  
  80.  
  81. ;*** Legal-ReadMe ***
  82. ;============================================================================
  83. ; ___________________________________________________________________________
  84. ; |*************************************************************************|
  85. ; |*|¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯|*|¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯|*|
  86. ; |*|               |*|  $Id: extra.library (30.05.04)                    |*|
  87. ; |*| ###### ###### |*|  RhoSigma Source based on NDK 3.1 Includes 40.15  |*|
  88. ; |*| ##  ## ##   # |*| _________________________________________________ |*|
  89. ; |*| ##  ##  ##    |*|                                                   |*|
  90. ; |*| ######   ##   |*|  Shared library with OS supporting functions      |*|
  91. ; |*| ##      ##    |*|                                                   |*|
  92. ; |*| ##     ##   # |*| ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯ |*|
  93. ; |*| ##     ###### |*|  Copyright © 1998-2004 RhoSigma, Roland Heyder    |*|
  94. ; |*|               |*|  All Rights Reserved.                             |*|
  95. ; |*|_______________|*|___________________________________________________|*|
  96. ; |*************************************************************************|
  97. ; ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  98. ; Die folgenden Worte beziehen sich auf das Projekt »extra.library«. Dieses
  99. ; Projekt beinhaltet folgende Dateien:
  100. ;
  101. ; Verzeichnis: Extra
  102. ; ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  103. ;  ReadMe          - was Sie gerade lesen
  104. ;  Install         - kopiert die Library ins LIBS:-Verzeichnis
  105. ;
  106. ; Verzeichnis: Extra/libs
  107. ; ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  108. ;  extra.lib_ocs   - der Programmcode (eine Shared-Library) OCS/ECS/AGA
  109. ;  extra.lib_cgx   - die CyberGraphX-fähige Variante der Library
  110. ;
  111. ; Verzeichnis: Extra/include/rhosigma
  112. ; ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  113. ;  extra_lib.fd    - Funktions- und Parameterdefinitionen
  114. ;
  115. ;  extradefs.i     - Definition von Konstanten (Assembler)
  116. ;  extra_lib.i     - die Library-Vector-Offsets (Assembler)
  117. ;
  118. ;  extradefs.h     - Definition von Konstanten (ANSI-C/C++)
  119. ;  extra_lib.h     - die amicall/libcall-Pragmas (ANSI-C/C++)
  120. ;  extra_protos.h  - die Prototypen der Funktionen (ANSI-C/C++)
  121. ;
  122. ;  extra.bh        - Header-File für div. BASICs (HBC-Compiler)
  123. ;  extra.bc        - Constants-File für div. BASICs (HBC-Compiler)
  124. ;  extra.bmap      - Hilfsdatei für div. BASICs
  125. ;
  126. ;  settings.i      - weitere globale Definitionen (Assembler)
  127. ;  settings.h      - weitere globale Definitionen (ANSI-C/C++)
  128. ;  settings.bc     - weitere globale Definitionen für BASIC
  129. ;
  130. ;  rhosigma.lib    - Link-Library mit Stubs und anderen Hilfs-Funktionen
  131. ;  rhosigma.h      - Prototypen & Defines für rhosigma.lib (ANSI-C/C++)
  132. ;
  133. ; Verzeichnis: Extra/Docs
  134. ; ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  135. ;  Extra.DOC       - Dokumentation extra.library (ASCII-Datei)
  136. ;  ExtraV34.guide  - Dokumentation extra.library (AmigaGuide® für OS 1.3+)
  137. ;  ExtraV39.guide  - Dokumentation extra.library (AmigaGuide® für OS 3.0+)
  138. ;
  139. ; Verzeichnis: Extra/Docs/HTML
  140. ; ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  141. ;  Main.html       - Startseite (ExtraV39.guide konvertiert nach HTML)
  142. ;
  143. ; Verzeichnis: Extra/Demos
  144. ; ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  145. ;  ShowMsgDemo.ASM - Beispiel für »extradefs.i« Assembler-Macros
  146. ;  ShowMsgDemo.C   - Beispiel für »extradefs.h« Macros & Funktionen (ANSI-C/C++)
  147. ;  ShowMsgDemo.BAS - Beispiel für »extra.bc« BASIC-Funktionen
  148. ;
  149. ;  StringDemo.BAS  - Beispiel für »extra.bc« String Funktion (ab v3.342)
  150. ;
  151. ;  AlertDemo.ASM   - Beispiel für »settings.i« Assembler-Macros
  152. ;  AlertDemo.C     - Beispiel für »settings.h« Macros & Funktionen (ANSI-C/C++)
  153. ;  AlertDemo.BAS   - Beispiel für »settings.bc« BASIC-Funktionen
  154. ;
  155. ;  Das Projekt »extra.library« ist (bis auf weiteres) als FREEWARE konzipiert
  156. ; und alle oben genannten Dateien werden im Rahmen des Programmpackets zur
  157. ; Verfügung gestellt.
  158. ;
  159. ;  Vertrieb zusammen mit kommerzieller Software bedarf jedoch meiner vorher
  160. ; eingeholten schriftlichen Zustimmung.
  161. ;
  162. ;  Die Funktionen der »normalen« Library sind alle schon auf einer Minimal-
  163. ; Konfiguration lauffähig, d.h. ab Kickstart-Release 1.2 (V33+), 68000er CPU
  164. ; und 512KB RAM.
  165. ;
  166. ;  Die »CGX/P96-Version« der Library benötigt jedoch als minimum mindestens
  167. ; Kickstart 2.0 (V36+). Des weiteren sollte die »cybergraphics.library« v40+
  168. ; bzw. die »Picasso96API.library« v2+ zur Verfügung stehen, was aber nicht
  169. ; zwingend erforderlich ist. Wenn die CGX/P96-Version der »extra.library« also
  170. ; auf einem System ohne installiertem CGX bzw. Picasso96 verwendet wird, dann
  171. ; wird dies erkannt, und auf die dementsprechend verfügbaren Custom-Chips
  172. ; zurückgegriffen.
  173. ;
  174. ;  Haben Sie einen Fehler entdeckt, oder haben Sie Erweiterungsvorschläge ??
  175. ; dann wenden Sie sich bitte an die folgende Adresse:
  176. ;
  177. ;                       MAIL: Roland Heyder
  178. ;                             Oberstadt 44
  179. ;                             38877 Benneckenstein
  180. ;                             Germany
  181. ;
  182. ;                      PHONE: +49 (0)39457 / 2540
  183. ;
  184. ;                        WWW: http://rhosigma.gmxhome.de
  185. ;
  186. ;                     E-MAIL: rhosigma@crosswinds.net
  187. ;                             rhosigma@gmx.net
  188. ;
  189. ; Nun viel Spaß mit der »extra.library« und vielen Dank für Ihr Interesse.
  190. ;============================================================================
  191.  
  192. ;*** Haftung ***
  193. ;============================================================================
  194. ;  Hiermit lehne ich ausdrücklich jegliche Haftung bzw. Verantwortung für
  195. ; Konsequenzen aller Art, die aus dem Gebrauch des Projektes »extra.library«
  196. ; resultieren, strikt ab.
  197. ;
  198. ;  Die »extra.library« wird Ihnen von mir so zur Verfügung gestellt, wie
  199. ; Sie sie vorgefunden haben. Das heißt, ich garantiere nicht, daß eventuelle
  200. ; Programmierfehler behoben werden, daß neue Versionen erscheinen, oder daß
  201. ; Sie Hilfe erhalten, falls bei Ihnen ein Fehler auftritt.
  202. ;
  203. ;  Obwohl die »extra.library« gründlich auf »Herz und Nieren« getestet wur-
  204. ; de, kann ich die Möglichkeit nicht ausschließen, daß die Library:
  205. ;  - aus irgendwelchen Gründen nicht kompatibel zu Ihrem Rechner ist
  206. ;  - Fehler enthält, die nur auf Ihrem Rechner auftreten
  207. ;  - auf Ihrem Rechner nicht die erwarteten Resultate liefert
  208. ;
  209. ;  Es liegt ausschließlich in Ihrer Verantwortung, alle notwendigen Sicher-
  210. ; heitsmaßnahmen zu treffen, um sich vor jeglichen schädlichen Auswirkungen
  211. ; bei der Nutzung der »extra.library« zu schützen.
  212. ;============================================================================
  213.  
  214. ;*** Hinweise ***
  215. ;============================================================================
  216. ; - Lassen Sie sich nicht davon verwirren, daß bei den Funktionen angegeben
  217. ;   ist, existent ab v1.323, v2.062 etc.. Es ist vollkommen ausreichend, wenn
  218. ;   Sie wie üblich beim OpenLibrary()-Aufruf die Version v1, v2 etc. angeben.
  219. ;   Denn auch wenn hier »krumme« Revisionsnummern angegeben sind, so handelt
  220. ;   es sich dabei jedoch immer um die jeweils 1. Veröffentlichung der neuen
  221. ;   Version, d.h. es ist z.B. keine v2.033 im Umlauf, weil eben v2.062 die 1.
  222. ;   Veröffentlichung der Version 2 überhaupt war. Und sowie neue Funktionen
  223. ;   hinzukommen, ändert sich auch wieder die Version. Ändert sich jedoch nur
  224. ;   die Revision, so handelt es sich nur um Optimierungen, Bugfixes o.ä., die
  225. ;   keine Veränderung der Funktionalität bedeuten. Ein explizites Testen der
  226. ;   Revision ist somit also unnötig.
  227. ;
  228. ; - Bei einigen Beschreibungen wird die Rede davon sein, daß irgendwelche
  229. ;   Daten, Pointer, Strukturen, Prefs etc. beim jeweils nächsten Aufruf einer
  230. ;   Funktion wieder überschrieben werden. Auch wenn dies eventuell an den be-
  231. ;   treffenden Stellen nicht 100%ig klar wird. DIES GILT NUR INNERHALB IHRES
  232. ;   LAUFENDEN TASKS !! - Sie brauchen also NICHT zu befürchten, daß Ihnen
  233. ;   irgendein anderer Task dadurch das Funktionsergebnis »versaut«, bevor Sie
  234. ;   dieses auswerten konnten. Es heißt ganz einfach nur, daß wenn IHR EIGENER
  235. ;   TASK im Verlaufe seiner Arbeit die Funktion erneut aufruft, dann über-
  236. ;   schreibt er damit das Ergebnis SEINES EIGENEN VORHERIGEN AUFRUFS dieser
  237. ;   Funktion. Da EIN Task nicht an mehreren Stellen im Code gleichzeitig aktiv
  238. ;   sein kann, kann es also keine Probleme geben.
  239. ;
  240. ; - Ich hoffe daß das oben eben schon ganz deutlich klar geworden, ja, die
  241. ;   Library ist, wie es normal auch sein sollte, vollkommen reentrant. D.h.
  242. ;   sie kann von mehreren Tasks/Prozessen gleichzeitig genutzt werden, ohne daß
  243. ;   sich negative Beeinflussungen (Interferrenzen) zwischen den einzelnen
  244. ;   Zugriffen entwickeln. Wo spezielle Bedingungen gelten, wird explizit in
  245. ;   den entsprechenden Beschreibungen darauf hingewiesen.
  246. ;
  247. ; - Sollten Sie im folgenden Text auf die Zeichenkombination »(+0)« treffen,
  248. ;   dann ist damit gemeint, daß der angegebene Parameter mit einem 0-Byte
  249. ;   abgeschlossen werden muß (z.B. Dateinamen etc.).
  250. ;    Wenn es sich jedoch um das Ergebnis einer Funktion handelt, dann können
  251. ;   Sie bei dieser Angabe davon ausgehen, daß dieses 0-terminiert ist.
  252. ;
  253. ; - Parameter des Typs BOOL sind normaler Weise TRUE bzw. FALSE. Ich habe
  254. ;   jedoch noch 3 neue Werte »erfunden« (UPPER/EQUAL/LOWER), deren Definition
  255. ;   Sie im mitgelieferten Includefile »settings.i« finden.
  256. ;
  257. ; - Für alle Parameter, die mit »An!« bzw. »Dn!« angegeben sind, tragen Sie
  258. ;   die volle Verantwortung, daß es sich wirklich um die von der Funktion
  259. ;   benötigten Daten handelt. Alle anderen Parameter werden intern überprüft.
  260. ;
  261. ; - Bei Funktionen, bei denen das Ergebnis mit »D0*« angegeben ist, handelt
  262. ;   es sich um Ergebnistestende Funktionen (s.a. Abschnitt »Details«).
  263. ;
  264. ; ACHTUNG: Die normalen Regeln beim Umgang mit Shared-Libraries sollten
  265. ; ¯¯¯¯¯¯¯¯ immer beachtet werden. Das heißt vor allem, daß Sie die Library
  266. ;          vor der Benutzung öffnen, und sich den Basiszeiger nicht etwa
  267. ;          aus der ExecBase.LibList holen. Die meisten Funktionen reagieren
  268. ;          mit dem DeadEnd-Alert »EL_Trespassed« (s. extradefs.i), wenn Sie
  269. ;          den Zugriff nicht vorher angemeldet haben.
  270. ;
  271. ; Zum Ende möchte ich noch sagen, daß Sie hier eine recht umfangreiche Doku-
  272. ; mentation vor sich haben, und wo viel Text ist, da sind sicher auch viele
  273. ; Fehler. Darum möchte ich Sie bitten, daß wenn Sie mich kontaktieren, dann
  274. ; nicht nur um mir zu sagen, daß ich hier oder dort einen Schreibfehler ge-
  275. ; macht habe !!
  276. ;============================================================================
  277.  
  278. ;*** Details ***
  279. ;============================================================================
  280. ; Hier noch einige technische Hintergrundinformationen für Interessierte.
  281. ;----------------------------------------------------------------------------
  282. ; - Die Library ist kein Produkt aus Hochsprachen-Modulen (C/C++, PASCAL etc.),
  283. ;   sondern ist zu ca.98% in Assembler (DevPac 3.04) verfasst. Außerdem finden
  284. ;   einige wenige Funktionen der amiga.lib v40.15 (Release 3.1) Verwendung.
  285. ;
  286. ; - Keine Scratch-Register: bei allen Funktionen bleiben sämtliche Register-
  287. ;   inhalte, außer der des Rückgaberegisters D0, erhalten (es sei denn, daß
  288. ;   die Funktion kein Ergebnis liefert, dann bleibt D0 auch erhalten).
  289. ;
  290. ; - Alle Funktionen, bei denen beim Ergebnis »D0*« angegeben ist, testen das
  291. ;   Ergebnis unmittelbar vorm Return auf NULL (tst.l d0).
  292. ;    Da der Returnbefehl (rts) die Flags nicht verändert, können Assembler-
  293. ;   programmierer nach dem Funktionsaufruf sofort den Condition-Code mittels
  294. ;   des Bcc-Befehls auswerten wenn die Funktion zurückkehrt, und brauchen nicht
  295. ;   noch selbst einen Testbefehl zu programmieren.
  296. ;
  297. ; - Zum Teil hochoptimierter Code (auch auf alter 68000er CPU), vor allem bei
  298. ;   zeitkritischen Funktionen.
  299. ;
  300. ; - Effektive Verwaltung der intern benötigten Speicherresourcen, wodurch
  301. ;   die meisten Funktionen auch bei stark fragmentierten Speicherlisten noch
  302. ;   immer lauffähig sind.
  303. ;
  304. ; - Das dynamische Puffersystem (DBS) sollte allen Programmierern von Editoren,
  305. ;   Datei-Managern o.ä. ein willkommenes Hilfsmittel sein. Der Speicher wird,
  306. ;   wie der Name schon sagt, dynamisch verwaltet, d.h. wie die RAM DISK, so
  307. ;   wird auch jeder Puffer in seiner Größe der gerade zu verwaltenden Daten-
  308. ;   menge (bis auf 4KB) genau angepasst.
  309. ;============================================================================
  310.  
  311. ;*** Danksagung ?? ***
  312. ;============================================================================
  313. ;  Nein, wohl eher nicht !! - Wenn ich Bilanz über die vergangenen 4 Jahre
  314. ; ziehe, in denen meine Arbeit als SHAREWARE zur Verfügung stand (und ich
  315. ; denke mit 5,- EUR im Gegensatz zu Projekten ähnlichen Umfangs sehr Preis-
  316. ; wert), dann kommen mir doch echte Zweifel, ob insbesondere es die Deutschen
  317. ; noch wert sind, daß man sich für sie den sprichwörtlichen Arsch aufreißt.
  318. ;
  319. ;  Zur »extra.library« sind mir in diesen 4 Jahren zum Teil mehrere Supportan-
  320. ; fragen von insgesamt 57 verschiedenen (deutschen) Leuten eingegangen (laut
  321. ; E-mail-Domain *.de bzw. Sprache, in der die Mails geschrieben waren). Alle
  322. ; haben irgendwas zu meckern gehabt, bezahlt jedoch hat nur EIN EINZIGER aus
  323. ; Deutschland. Kurz um, jeder wollte, daß speziell für ihn Anpassungen vor-
  324. ; genommen werden, wollte dies jedoch zum Nulltarif od. am besten wohl noch
  325. ; ein paar Euros von meiner Seite dazu. Leute, ich kann nur sagen, so läuft's
  326. ; nicht, so kommen wir hier in Deutschland aus unserer Kriese nie mehr raus.
  327. ;
  328. ;  Besonders beschähmend für Deutschland und die Deutschen als solche ist da-
  329. ; bei die Tatsache, daß die restlichen 8 Registrierungen für die Library aus-
  330. ; schließlich aus den Ost-Europäischen Ländern kamen, und die Leute dort haben
  331. ; garantiert noch 3 mal weniger Geld in der Tasche als wir hier, aber zumindest
  332. ; haben sie noch Ehre, Anstand und Würde und wissen, daß man für in Anspruch
  333. ; Genommenes auch zahlt. Und genau diese Eigenschaften gehen weit über das hin-
  334. ; aus, als das, was ich gegenwärtig hier bei uns Deutschen in den alltäglichen
  335. ; Umgangsformen noch erkenne !!
  336. ;
  337. ;  Daß man im Amiga-Markt heutzutage keine Rekordumsätze mehr erwarten kann,
  338. ; das war ja von vornherein klar und mit 5,- EUR Sharegebühr auf der anderen
  339. ; Seite auch gar nicht beabsichtigt. Aber ganze 9 Registrierungen über einen
  340. ; Zeitraum von 4 Jahren zeigt ein absolutes Desinteresse an der weiteren
  341. ; Unterstützung, was dann Wohl oder Übel doch bedeutet, daß ich dem Amiga
  342. ; nach langer Treue nun letztendlich doch den Rücken zukehren werde.
  343. ;
  344. ;  Gleiches gilt übrigens auch für Deutschland, wenn ich nicht bald ein paar
  345. ; positive Eigenschaften in seiner Bevölkerung wiederentdecken werde. Einfach
  346. ; immer nur den anderen, den Politikern, Großindustriellen etc. die Schuld
  347. ; an allem zu geben, das ist nicht der Weg aller Dinge. Jeder kann was tun,
  348. ; jedoch nur wenn er sich nicht immer weiter und weiter in Ärger, Wut und
  349. ; Desillusion über die gegenwärtige Lage verliert. Nicht meckern ist das Motto,
  350. ; sondern erst mal besser machen, dann verdient man sich auch das Recht mal
  351. ; zu meckern ...
  352. ;============================================================================
  353.  
  354. ;*** extra.library / BAMCheckSum()           (OFFSET -42) V1.323 ***
  355. ;============================================================================
  356. ; Diese Funktion berechnet die Checksumme eines Bitmap-Blocks innerhalb
  357. ; eines der gängigen Amiga-FileSysteme (DOS/0 - DOS/5), welches eine Block-
  358. ; größe von 512 Bytes verwendet (z.B. normale Disketten).
  359. ;----------------------------------------------------------------------------
  360. ; Synopsis:    success = BAMCheckSum (Block)
  361. ;                D0*                   A0!
  362. ;
  363. ; Eingaben:    A0 --> APTR auf die Startadresse des Blocks (gerade Adresse,
  364. ;                          sonst folgt Fehler)
  365. ;
  366. ; Ergebnis:    D0 --> BOOL - TRUE , wenn alles in Ordnung
  367. ;                          - FALSE, wenn Startadresse ungerade war
  368. ;
  369. ; Bemerkung:   Die Summe wird gleich ordnungsgemäß in den Block geschrieben,
  370. ;              so daß er anschließend sofort gespeichert werden kann.
  371. ;
  372. ; Siehe auch:  »BootBlockSum()«, »DiskBlockSum()«
  373. ;============================================================================
  374.  
  375. ;*** extra.library / BootBlockSum()          (OFFSET -48) V1.323 ***
  376. ;============================================================================
  377. ; Diese Funktion berechnet die Checksumme eines Boot-Blocks innerhalb eines
  378. ; der gängigen Amiga-FileSysteme (DOS/0 - DOS/5), welches eine Blockgröße
  379. ; von 512 Bytes verwendet (z.B. normale Disketten).
  380. ;----------------------------------------------------------------------------
  381. ; Synopsis:    success = BootBlockSum (Block)
  382. ;                D0*                    A0!
  383. ;
  384. ; Eingaben:    A0 --> APTR auf die Startadresse des Blocks (gerade Adresse,
  385. ;                          sonst folgt Fehler)
  386. ;
  387. ; Ergebnis:    D0 --> BOOL - TRUE , wenn alles in Ordnung
  388. ;                          - FALSE, wenn Startadresse ungerade war
  389. ;
  390. ; Bemerkung:   Beachten Sie, daß den Boot-Block eigentlich zwei hinterein-
  391. ;              ander auf der Diskette liegende Blöcke darstellen (Block 0-1).
  392. ;              Auch bei der Berechnung müssen beide Blöcke unmittelbar hin-
  393. ;              tereinander im Speicher liegen.
  394. ;              Die Summe wird gleich ordnungsgemäß in den Block geschrie-
  395. ;              ben, so daß er anschließend sofort gespeichert werden kann.
  396. ;
  397. ; Siehe auch:  »BAMCheckSum()«, »DiskBlockSum()«
  398. ;============================================================================
  399.  
  400. ;*** extra.library / DiskBlockSum()          (OFFSET -54) V1.323 ***
  401. ;============================================================================
  402. ; Diese Funktion berechnet die Checksumme eines beliebigen Blocks innerhalb
  403. ; eines der gängigen Amiga-FileSysteme (DOS/0 - DOS/5), welches eine Block-
  404. ; größe von 512 Bytes verwendet (z.B. normale Disketten), der KEINEN Boot-Block
  405. ; und KEINEN Bitmap-Block darstellt.
  406. ;----------------------------------------------------------------------------
  407. ; Synopsis:    success = DiskBlockSum (Block)
  408. ;                D0*                    A0!
  409. ;
  410. ; Eingaben:    A0 --> APTR auf die Startadresse des Blocks (gerade Adresse,
  411. ;                          sonst folgt Fehler)
  412. ;
  413. ; Ergebnis:    D0 --> BOOL - TRUE , wenn alles in Ordnung
  414. ;                          - FALSE, wenn Startadresse ungerade war
  415. ;
  416. ; Bemerkung:   Die Summe wird gleich ordnungsgemäß in den Block geschrieben,
  417. ;              so daß er anschließend sofort gespeichert werden kann.
  418. ;
  419. ;   ACHTUNG:   Handelt es sich um ein FastFile-System (DOS/1, DOS/3, DOS/5),
  420. ;   ¯¯¯¯¯¯¯¯   dann darf diese Funktion NICHT auf Data-Blöcke angewendet
  421. ;              werden, da diese beim FFS keine Checksummen enthalten.
  422. ;              Nichtbeachtung führt zu Datenverlust, für den ich KEINERLEI
  423. ;              HAFTUNG übernehme !!
  424. ;
  425. ; Siehe auch:  »BAMCheckSum()«, »BootBlockSum()«
  426. ;============================================================================
  427.  
  428. ;*** extra.library / OpenBuf()               (OFFSET -60) V1.323 ***
  429. ;============================================================================
  430. ; Diese Funktion baut einen neuen dynamischen Puffer auf, und führt alle
  431. ; nötigen Initialisierungen durch. Als Ergebnis erhalten Sie einen Zeiger,
  432. ; der bei allen Pufferfunktionen als Identifikation dieses Puffers dient.
  433. ;----------------------------------------------------------------------------
  434. ; Synopsis:    bufHandle = OpenBuf (VOID)
  435. ;                 D0*
  436. ;
  437. ; Ergebnis:    D0 --> APTR - auf den initialisierten BufHandle
  438. ;                          - 0-PTR, wenn Fehler (Info mit »LastError()«)
  439. ;
  440. ; Bemerkung:   Jeder geöffnete Puffer sollte, wenn er nicht mehr benötigt
  441. ;              wird, mittels »CloseBuf()« wieder geschlossen werden bzw.
  442. ;              wenigstens mittels der Funktion »ClearBuf()« auf minimalen
  443. ;              Speicherverbrauch reduziert werden.
  444. ;
  445. ;   ACHTUNG:   Wenn Sie sich Puffer mit anderen Prozessen teilen, dann liegt
  446. ;   ¯¯¯¯¯¯¯¯   es ausschließlich in Ihrer Verantwortung, Zugriffe auf diese
  447. ;              Puffer so zu koordinieren und zu sichern, daß die Prozesse im
  448. ;              Rahmen des Multitaskings nicht gleichzeitig auf die Puffer zu-
  449. ;              greifen können !! - Achten Sie immer darauf, daß jede Puffer-
  450. ;              funktion vollständig abgeschlossen wurde, bevor ein anderer
  451. ;              Prozess die nächste startet.
  452. ;
  453. ; Siehe auch:  »CloseBuf()«, »FileToBuf()«, »BufToFile()«, »ClearBuf()«,
  454. ;              »DuplicateBuf()«, »BufInfo()«
  455. ;
  456. ;----------------------------------------------------------------------------
  457. ;--- Veränderungen seit v2.062 ----------------------------------------------
  458. ;----------------------------------------------------------------------------
  459. ;
  460. ; Bemerkung:   Diese Funktion ist veraltet, bitte benutzen Sie stattdessen
  461. ;              die Funktion »v2_OpenBuf()«, welche zusätzlich die Angabe von
  462. ;              Speicher-Flags ermöglicht, um z.B. Audio- oder Grafik-Daten
  463. ;              gezielt ins CHIP-Ram zu verlagern.
  464. ;
  465. ;   ACHTUNG:   Diese Funktion bleibt aus kompatiblitätsgründen nach wie vor
  466. ;   ¯¯¯¯¯¯¯¯   unverändert wie oben beschrieben erhalten und funktionsfähig,
  467. ;              jedoch hat und wird diese Funktion immer nur PUBLIC-Memory für
  468. ;              den Datenbereich verwenden, und unterliegt der durch das System
  469. ;              festgelegten Zuordnungsreihenfolge (meist FAST vor CHIP) !!
  470. ;
  471. ; Siehe auch:  »v2_FileToBuf()«, »v2_DuplicateBuf()«
  472. ;============================================================================
  473.  
  474. ;*** extra.library / v2_OpenBuf()            (OFFSET -300) V2.062 ***
  475. ;============================================================================
  476. ; Diese Funktion baut einen neuen dynamischen Puffer auf, und führt alle
  477. ; nötigen Initialisierungen durch. Dabei kann noch angegeben werden, welcher
  478. ; Speichertyp für den Datenbereich verwendet werden soll. Als Ergebnis erhalten
  479. ; Sie einen Zeiger, der bei allen weiteren Pufferfunktionen als Identifikation
  480. ; dieses Puffers dient.
  481. ;----------------------------------------------------------------------------
  482. ; Synopsis:    bufHandle = v2_OpenBuf (MemType)
  483. ;                 D0*                    D0!
  484. ;
  485. ; Eingaben:    D0 --> ULONG eine Kombination von Speicher-Flags wie sie in
  486. ;                           der Include-Datei »exec/memory.i« definiert sind.
  487. ;
  488. ; Ergebnis:    D0 --> APTR - auf den initialisierten BufHandle
  489. ;                          - 0-PTR, wenn Fehler (Info mit »LastError()«)
  490. ;
  491. ;   ACHTUNG:   Hinsichtlich des Puffer-Handlings bzw. -Sharings gelten die
  492. ;   ¯¯¯¯¯¯¯¯   gleichen Konditionen wie bei »OpenBuf()«
  493. ;
  494. ; Siehe auch:  »v2_FileToBuf()«, »v2_DuplicateBuf()«
  495. ;============================================================================
  496.  
  497. ;*** extra.library / CloseBuf()              (OFFSET -66) V1.323 ***
  498. ;============================================================================
  499. ; Diese Funktion schließt den angegebenen Puffer und gibt alle damit ver-
  500. ; bundenen Speicherresourcen an das System zurück. Nach Aufruf dieser Funk-
  501. ; tion können keine weiteren Pufferfunktionen mehr auf den angegebenen
  502. ; BufHandle ausgeführt werden.
  503. ;----------------------------------------------------------------------------
  504. ; Synopsis:    success = CloseBuf (BufHandle)
  505. ;                D0*                  A0
  506. ;
  507. ; Eingaben:    A0 --> APTR auf den zu schließenden BufHandle
  508. ;
  509. ; Ergebnis:    D0 --> BOOL - TRUE , wenn alles in Ordnung
  510. ;                          - FALSE, wenn Fehler (Info mit »LastError()«)
  511. ;
  512. ;   ACHTUNG:   Wenn ein Task die »extra.library« ENDGÜLTIG schließt (es kann
  513. ;   ¯¯¯¯¯¯¯¯   ja sein, daß mehrere Open-Aufrufe verschachtelt wurden), dann
  514. ;              werden automatisch alle noch offenen Puffer, die DIESER TASK
  515. ;              geöffnet hat (egal, mit welcher Funktion) wieder geschlossen.
  516. ;              Diese Funktion löscht automatisch die Prozessor-Caches.
  517. ;
  518. ; Siehe auch:  »OpenBuf()«, »FileToBuf()«, »BufToFile()«, »ClearBuf()«,
  519. ;              »DuplicateBuf()«, »BufInfo()«
  520. ;============================================================================
  521.  
  522. ;*** extra.library / FileToBuf()             (OFFSET -72) V1.323 ***
  523. ;============================================================================
  524. ; Diese Funktion läd die Datei mit dem angegebenen Namen in einen neuen dy-
  525. ; namischen Puffer. Es wird der fertig initialisierte BufHandle des neu an-
  526. ; gelegten Puffers zurückgegeben. Die aktuelle Cursorposition steht nach dem
  527. ; Laden auf dem Pufferanfang (Pos. 0).
  528. ;----------------------------------------------------------------------------
  529. ; Synopsis:    bufHandle = FileToBuf (FileName)
  530. ;                 D0*                   A0!
  531. ;
  532. ; Eingaben:    A0 --> STRPTR auf einen AmigaDOS-Dateinamen(+0)
  533. ;
  534. ; Ergebnis:    D0 --> APTR - auf den neu initialisierten BufHandle
  535. ;                          - 0-PTR, wenn Fehler (Info mit »LastError()«)
  536. ;
  537. ; Bemerkung:   Ein mittels dieser Funktion geöffneter Puffer wird ebenfalls
  538. ;              mit »CloseBuf()« wieder geschlossen.
  539. ;              Diese Funktion löscht automatisch die Prozessor-Caches.
  540. ;
  541. ;   ACHTUNG:   Diese Funktion darf NUR von vollwertigen DOS-Prozessen auf-
  542. ;   ¯¯¯¯¯¯¯¯   gerufen werden. Ein normaler EXEC-Task ist nicht ausreichend.
  543. ;
  544. ; Siehe auch:  »OpenBuf()«, »CloseBuf()«, »BufToFile()«, »ClearBuf()«,
  545. ;              »DuplicateBuf()«, »BufInfo()«
  546. ;
  547. ;----------------------------------------------------------------------------
  548. ;--- Veränderungen seit v2.062 ----------------------------------------------
  549. ;----------------------------------------------------------------------------
  550. ;
  551. ; Bemerkung:   Diese Funktion ist veraltet, bitte benutzen Sie stattdessen
  552. ;              die Funktion »v2_FileToBuf()«, welche zusätzlich die Angabe von
  553. ;              Speicher-Flags ermöglicht, um z.B. Audio- oder Grafik-Daten
  554. ;              gezielt ins CHIP-Ram zu laden.
  555. ;
  556. ;   ACHTUNG:   Diese Funktion bleibt aus kompatiblitätsgründen nach wie vor
  557. ;   ¯¯¯¯¯¯¯¯   unverändert wie oben beschrieben erhalten und funktionsfähig,
  558. ;              jedoch hat und wird diese Funktion immer nur PUBLIC-Memory für
  559. ;              den Datenbereich verwenden, und unterliegt der durch das System
  560. ;              festgelegten Zuordnungsreihenfolge (meist FAST vor CHIP) !!
  561. ;
  562. ; Siehe auch:  »v2_OpenBuf()«, »v2_DuplicateBuf()«
  563. ;============================================================================
  564.  
  565. ;*** extra.library / v2_FileToBuf()          (OFFSET -306) V2.062 ***
  566. ;============================================================================
  567. ; Diese Funktion läd die Datei mit dem angegebenen Namen in einen neuen dy-
  568. ; namischen Puffer. Dabei kann noch angegeben werden, welcher Speichertyp für
  569. ; den Datenbereich verwendet werden soll. Es wird der fertig initialisierte
  570. ; BufHandle des neu angelegten Puffers zurückgegeben. Die aktuelle Cursorpo-
  571. ; sition steht nach dem Laden auf dem Pufferanfang (Pos. 0).
  572. ;----------------------------------------------------------------------------
  573. ; Synopsis:    bufHandle = v2_FileToBuf (FileName, MemType)
  574. ;                 D0*                      A0!       D0!
  575. ;
  576. ; Eingaben:    A0 --> STRPTR auf einen AmigaDOS-Dateinamen(+0)
  577. ;              D0 --> ULONG  eine Kombination von Speicher-Flags wie sie in
  578. ;                            der Include-Datei »exec/memory.i« definiert sind.
  579. ;
  580. ; Ergebnis:    D0 --> APTR - auf den neu initialisierten BufHandle
  581. ;                          - 0-PTR, wenn Fehler (Info mit »LastError()«)
  582. ;
  583. ;   ACHTUNG:   Hinsichtlich des Puffer-Handlings gelten die gleichen Kon-
  584. ;   ¯¯¯¯¯¯¯¯   ditionen wie bei »FileToBuf()«
  585. ;
  586. ; Siehe auch:  »v2_OpenBuf()«, »v2_DuplicateBuf()«
  587. ;============================================================================
  588.  
  589. ;*** extra.library / BufToFile()             (OFFSET -78) V1.323 ***
  590. ;============================================================================
  591. ; Diese Funktion schreibt den gesamten Datenbereich des durch den BufHandle
  592. ; spezifizierten Puffers in eine Datei mit dem angegebenen Namen.
  593. ;----------------------------------------------------------------------------
  594. ; Synopsis:    written = BufToFile (BufHandle, FileName)
  595. ;                D0*                   A0        A1!
  596. ;
  597. ; Eingaben:    A0 --> APTR   auf den gewünschten BufHandle
  598. ;              A1 --> STRPTR auf einen AmigaDOS-Dateinamen(+0)
  599. ;
  600. ; Ergebnis:    D0 --> LONG - Anzahl der geschriebenen Bytes
  601. ;                          - negativ, wenn Fehler (Info mit »LastError()«)
  602. ;
  603. ; Bemerkung:   Ist beim Schreiben der Datei ein Fehler aufgetreten, dann wird
  604. ;              die unvollständige (fehlerhafte) Datei gleich wieder gelöscht.
  605. ;
  606. ;   ACHTUNG:   Diese Funktion darf NUR von vollwertigen DOS-Prozessen auf-
  607. ;   ¯¯¯¯¯¯¯¯   gerufen werden. Ein normaler EXEC-Task ist nicht ausreichend.
  608. ;
  609. ; Siehe auch:  »OpenBuf()«, »CloseBuf()«, »FileToBuf()«, »ClearBuf()«,
  610. ;              »DuplicateBuf()«, »BufInfo()«
  611. ;============================================================================
  612.  
  613. ;*** extra.library / ClearBuf()              (OFFSET -84) V1.323 ***
  614. ;============================================================================
  615. ; Diese Funktion löscht den gesamten Inhalt des angegebenen Puffers, und
  616. ; reduziert dessen Speicherbedarf auf ein Minimum von 4KB. Außerdem werden,
  617. ; wenn vorhanden, auch die internen Kopien aller Such-Daten wieder freige-
  618. ; geben sowie die gesetzten Bookmarks gelöscht und der Curser auf Pos.0 gesetzt.
  619. ; Der Puffer ist nach dieser Funktion also genau in dem Zustand, als wenn er
  620. ; gerade mit »OpenBuf()« geöffnet worden wäre.
  621. ;----------------------------------------------------------------------------
  622. ; Synopsis:    success = ClearBuf (BufHandle)
  623. ;                D0*                  A0
  624. ;
  625. ; Eingaben:    A0 --> APTR auf den BufHandle des zu löschenden Puffers
  626. ;
  627. ; Ergebnis:    D0 --> BOOL - TRUE , wenn alles in Ordnung
  628. ;                          - FALSE, wenn Fehler (Info mit »LastError()«)
  629. ;
  630. ; Bemerkung:   Diese Funktion löscht automatisch die Prozessor-Caches.
  631. ;
  632. ; Siehe auch:  »OpenBuf()«, »CloseBuf()«, »FileToBuf()«, »BufToFile()«,
  633. ;              »DuplicateBuf()«, »BufInfo()«
  634. ;============================================================================
  635.  
  636. ;*** extra.library / DuplicateBuf()          (OFFSET -90) V1.323 ***
  637. ;============================================================================
  638. ; Diese Funktion erstellt einen neuen dynamischen Puffer, dessen Daten eine
  639. ; genaue Kopie des angegebenen Quell-Puffers darstellen. Das heißt, es wer-
  640. ; den nicht nur die regulären Daten kopiert, sondern auch die Such-Daten so-
  641. ; wie die Bookmarks. Außerdem wird auch die aktuelle Cursorposition von dem
  642. ; Quell-Puffer übernommen. Sie erhalten als Ergebnis einen Zeiger auf den
  643. ; neu initialisierten BufHandle.
  644. ;----------------------------------------------------------------------------
  645. ; Synopsis:    bufHandle = DuplicateBuf (BufHandle)
  646. ;                 D0*                        A0
  647. ;
  648. ; Eingaben:    A0 --> APTR BufHandle des zu duplizierenden Puffers
  649. ;
  650. ; Ergebnis:    D0 --> APTR - Zeiger auf den neu initialisierten BufHandle
  651. ;                          - 0-PTR, wenn Fehler (Info mit »LastError()«)
  652. ;
  653. ; Bemerkung:   Auch ein mittels dieser Funktion geöffneter Puffer wird mit
  654. ;              der Funktion »CloseBuf()« wieder geschlossen.
  655. ;              Diese Funktion löscht automatisch die Prozessor-Caches.
  656. ;
  657. ; Siehe auch:  »OpenBuf()«, »CloseBuf()«, »FileToBuf()«, »BufToFile()«,
  658. ;              »ClearBuf()«, »BufInfo()«
  659. ;
  660. ;----------------------------------------------------------------------------
  661. ;--- Veränderungen seit v2.062 ----------------------------------------------
  662. ;----------------------------------------------------------------------------
  663. ;
  664. ; Bemerkung:   Diese Funktion ist veraltet, bitte benutzen Sie stattdessen
  665. ;              die Funktion »v2_DuplicateBuf()«, welche zusätzlich die Angabe
  666. ;              von Speicher-Flags ermöglicht, um z.B. Audio- oder Grafik-Daten
  667. ;              gezielt ins CHIP-Ram zu duplizieren.
  668. ;
  669. ;   ACHTUNG:   Diese Funktion bleibt aus kompatiblitätsgründen nach wie vor
  670. ;   ¯¯¯¯¯¯¯¯   unverändert wie oben beschrieben erhalten und funktionsfähig,
  671. ;              jedoch hat und wird diese Funktion immer DEN GLEICHEN Speicher-
  672. ;              typ für den Datenbereich des neuen Puffers verwenden wie der
  673. ;              originale Puffer auch verwendet.
  674. ;
  675. ; Siehe auch:  »v2_OpenBuf()«, »v2_FileToBuf()«
  676. ;============================================================================
  677.  
  678. ;*** extra.library / v2_DuplicateBuf()       (OFFSET -312) V2.062 ***
  679. ;============================================================================
  680. ; Diese Funktion erstellt einen neuen dynamischen Puffer, dessen Daten eine
  681. ; genaue Kopie des angegebenen Quell-Puffers darstellen. Das heißt, es wer-
  682. ; den nicht nur die regulären Daten kopiert, sondern auch die Such-Daten so-
  683. ; wie die Bookmarks. Außerdem wird auch die aktuelle Cursorposition von dem
  684. ; Quell-Puffer übernommen. Dabei kann noch angegeben werden, welcher Speicher-
  685. ; typ für den Datenbereich verwendet werden soll. Sie erhalten als Ergebnis
  686. ; einen Zeiger auf den neu initialisierten BufHandle.
  687. ;----------------------------------------------------------------------------
  688. ; Synopsis:    bufHandle = v2_DuplicateBuf (BufHandle, MemType)
  689. ;                 D0*                          A0        D0!
  690. ;
  691. ; Eingaben:    A0 --> APTR  BufHandle des zu duplizierenden Puffers
  692. ;              D0 --> ULONG eine Kombination von Speicher-Flags wie sie in
  693. ;                           der Include-Datei »exec/memory.i« definiert sind.
  694. ;
  695. ; Ergebnis:    D0 --> APTR - Zeiger auf den neu initialisierten BufHandle
  696. ;                          - 0-PTR, wenn Fehler (Info mit »LastError()«)
  697. ;
  698. ;   ACHTUNG:   Hinsichtlich des Puffer-Handlings gelten die gleichen Kon-
  699. ;   ¯¯¯¯¯¯¯¯   ditionen wie bei »DuplicateBuf()«
  700. ;
  701. ; Siehe auch:  »v2_OpenBuf()«, »v2_FileToBuf()«
  702. ;============================================================================
  703.  
  704. ;*** extra.library / BufInfo()               (OFFSET -96) V1.323 ***
  705. ;============================================================================
  706. ; Mit dieser Funktion können Sie sich spezifische Daten über den momentanen
  707. ; Zustand eines Puffers holen. Als Ergebnis erhalten Sie einen Adress-Zeiger
  708. ; auf eine entsprechend ausgefüllte »BufInfoBlock«-Struktur (s. extradefs.i).
  709. ;----------------------------------------------------------------------------
  710. ; Synopsis:    BIBStruct = BufInfo (BufHandle)
  711. ;                 D0*                  A0
  712. ;
  713. ; Eingaben:    A0 --> APTR auf den gewünschten BufHandle
  714. ;
  715. ; Ergebnis:    D0 --> APTR - auf ausgefüllte »BIBStruct« (s. extradefs.i)
  716. ;                          - 0-PTR, wenn Fehler (Info mit »LastError()«)
  717. ;
  718. ; Bemerkung:   Sie brauchen sich nicht um die Beschaffung bzw. Freigabe des
  719. ;              »BufInfoBlocks« zu kümmern, da der benötigte Speicherplatz
  720. ;              Ihrem Task beim Öffnen der »extra.library« zur Verfügung ge-
  721. ;              stellt wird, und dann beim Schließen der Library auch automa-
  722. ;              tisch wieder freigegeben wird. Beachten Sie jedoch, daß die
  723. ;              Struktur aufgrund dieser Verwaltungsmethode beim jeweils
  724. ;              nächsten Aufruf dieser Funktion wieder überschrieben wird.
  725. ;
  726. ;   ACHTUNG:   In C und C++ ist das APTR-Ergebnis als Typ STRUCT *BIBStruct
  727. ;   ¯¯¯¯¯¯¯¯   zu behandeln.
  728. ;
  729. ; Siehe auch:  »OpenBuf()«, »CloseBuf()«, »FileToBuf()«, »BufToFile()«,
  730. ;              »ClearBuf()«, »DuplicateBuf()«
  731. ;============================================================================
  732.  
  733. ;*** extra.library / SeekBuf()               (OFFSET -102) V1.323 ***
  734. ;============================================================================
  735. ; Mit dieser Funktion können Sie die aktuelle Cursorposition innerhalb des
  736. ; angegebenen Puffers an jede beliebige Stelle setzten, und damit bestimmen,
  737. ; wo im Puffer die folgende(n) Pufferoperation(en) wirken soll(en). Es wird
  738. ; zuerst die durch den »Mode« angegebene Positionierung durchgeführt, und
  739. ; dann der Offsetwert »Position«, welcher sowohl positiv, als auch negativ
  740. ; sein darf, zu dieser Position hinzuaddiert.
  741. ;----------------------------------------------------------------------------
  742. ; Synopsis:    oldPos = SeekBuf (BufHandle, Position, Mode)
  743. ;                D0*                A0         D0      D1
  744. ;
  745. ; Eingaben:    A0 --> APTR  auf den gewünschten BufHandle
  746. ;              D0 --> LONG  Offset, der zu der durch den »Mode« spezifizier-
  747. ;                           ten Position addiert wird (positiv od. negativ)
  748. ;              D1 --> ULONG der zu verwendende »Mode« (s. extradefs.i)
  749. ;
  750. ; Ergebnis:    D0 --> LONG - alte Position, wenn alles in Ordnung
  751. ;                             (ACHTUNG: Zählbeginn = 0 !!)
  752. ;                          - negativ, wenn Fehler (Info mit »LastError()«)
  753. ;
  754. ; Bemerkung:   Mit dieser Funktion können Sie außerdem schnell die aktuelle
  755. ;              Cursorposition ermitteln, wenn Ihnen der Weg über »BufInfo()«
  756. ;              zu aufwendig ist. Setzen Sie zu diesem Zweck den Parameter
  757. ;              »Mode« auf »SKM_Current«, und den Parameter »Position« auf
  758. ;              NULL. Mit diesem Aufruf bleibt die aktuelle Cursorposition
  759. ;              tatsächlich zwar unverändert, Sie bekommen sie aber auch als
  760. ;              angeblich alte Position zurückgeliefert.
  761. ;
  762. ;   ACHTUNG:   Wenn ein Fehler auftritt, dann bleibt die alte Cursor-
  763. ;   ¯¯¯¯¯¯¯¯   position erhalten !!
  764. ;
  765. ; Siehe auch:  »Store()«, »InsertBuf()«, »InsertFile()«, »Replace()«,
  766. ;              »Get()«, »Clear()«
  767. ;============================================================================
  768.  
  769. ;*** extra.library / Store()                 (OFFSET -108) V1.323 ***
  770. ;============================================================================
  771. ; Diese Funktion schreibt die angegebenen Daten in den durch den BufHandle
  772. ; spezifizierten Puffer. Die Daten werden an der aktuellen Cursorposition
  773. ; eingefügt. Eventuell schon vorhandene Daten an dieser Stelle werden ent-
  774. ; sprechend nach hinten verschoben. Die aktuelle Cursorposition wird auto-
  775. ; matisch nachgeführt, und steht nach dem Aufruf dementsprechend auf dem er-
  776. ; sten Byte nach den eingefügten Daten.
  777. ;----------------------------------------------------------------------------
  778. ; Synopsis:    newPos = Store (BufHandle, Data, Size)
  779. ;               D0*               A0      A1!    D0
  780. ;
  781. ; Eingaben:    A0 --> APTR  auf den gewünschten BufHandle
  782. ;              A1 --> APTR  auf die einzufügenden Daten
  783. ;              D0 --> ULONG Menge der Daten in Bytes
  784. ;
  785. ; Ergebnis:    D0 --> LONG - die neue Cursorposition, wenn alles in Ordnung
  786. ;                             (ACHTUNG: Zählbeginn = 0 !!)
  787. ;                          - negativ, wenn Fehler (Info mit »LastError()«)
  788. ;
  789. ; Bemerkung:   Diese Funktion löscht automatisch die Prozessor-Caches.
  790. ;
  791. ; Siehe auch:  »SeekBuf()«, »InsertBuf()«, »InsertFile()«, »Replace()«,
  792. ;              »Get()«, »Clear()«
  793. ;============================================================================
  794.  
  795. ;*** extra.library / InsertBuf()             (OFFSET -114) V1.323 ***
  796. ;============================================================================
  797. ; Diese Funktion fügt die Daten eines anderen, bereits bestehenden Puffers,
  798. ; an der aktuellen Cursorposition des gewünschten Puffers ein. Dies ist von
  799. ; Nutzen, wenn viele Einzeldaten am Anfang eines Puffers eingefügt werden
  800. ; sollen, was nämlich je nach Menge der nach hinten zu schiebenden Daten eine
  801. ; sehr zeitraubende Angelegenheit werden kann. In solchen Fällen öffnen Sie
  802. ; einfach einen neuen Puffer, wo Sie die Daten dann fortlaufend (also immer
  803. ; ans Pufferende anfügend) speichern können, wobei nichts nach hinten gescho-
  804. ; ben werden muß. Ist das getan, dann verwenden Sie diese Funktion, um die
  805. ; Daten nun in Ihren eigentlichen Arbeitspuffer einzufügen, womit jetzt nur
  806. ; einmal die ganzen Restdaten verschoben werden müssen. Die Cursorposition
  807. ; wird automatisch nachgeführt, und steht nach dem Aufruf dementsprechend auf
  808. ; dem ersten Byte nach den eingefügten Daten.
  809. ;----------------------------------------------------------------------------
  810. ; Synopsis:    inserted = InsertBuf (BufHandle1, BufHandle2)
  811. ;                D0*                     A0          A1
  812. ;
  813. ; Eingaben:    A0 --> APTR auf den gewünschten Ziel-BufHandle
  814. ;              A1 --> APTR auf den zu verwendenden Quell-BufHandle
  815. ;
  816. ; Ergebnis:    D0 --> LONG - Anzahl der eingefügten Bytes
  817. ;                          - negativ, wenn Fehler (Info mit »LastError()«)
  818. ;
  819. ; Bemerkung:   Diese Funktion löscht automatisch die Prozessor-Caches.
  820. ;
  821. ; Siehe auch:  »SeekBuf()«, »Store()«, »InsertFile()«, »Replace()«, »Get()«,
  822. ;              »Clear()«
  823. ;============================================================================
  824.  
  825. ;*** extra.library / InsertFile()            (OFFSET -120) V1.323 ***
  826. ;============================================================================
  827. ; Diese Funktion fügt die Daten der angegebenen Datei in den gewünschten
  828. ; Puffer an der aktuellen Cursorposition ein. Die Cursorposition wird auto-
  829. ; matisch nachgeführt, und steht nach dem Aufruf dementsprechend auf dem er-
  830. ; sten Byte nach den eingefügten Daten.
  831. ;----------------------------------------------------------------------------
  832. ; Synopsis:    inserted = InsertFile (BufHandle, FileName)
  833. ;                D0*                     A0        A1!
  834. ;
  835. ; Eingaben:    A0 --> APTR   auf den gewünschten BufHandle
  836. ;              A1 --> STRPTR auf einen AmigaDOS-Dateinamen(+0)
  837. ;
  838. ; Ergebnis:    D0 --> LONG - Anzahl der eingefügten Bytes
  839. ;                          - negativ, wenn Fehler (Info mit »LastError()«)
  840. ;
  841. ; Bemerkung:   Diese Funktion löscht automatisch die Prozessor-Caches.
  842. ;
  843. ;   ACHTUNG:   Diese Funktion darf NUR von vollwertigen DOS-Prozessen auf-
  844. ;   ¯¯¯¯¯¯¯¯   gerufen werden. Ein normaler EXEC-Task ist nicht ausreichend.
  845. ;
  846. ; Siehe auch:  »SeekBuf()«, »Store()«, »InsertBuf()«, »Replace()«, »Get()«,
  847. ;              »Clear()«
  848. ;============================================================================
  849.  
  850. ;*** extra.library / Replace()               (OFFSET -126) V1.323 ***
  851. ;============================================================================
  852. ; Mit dieser Funktion können Sie die Daten an der aktuellen Cursorposition
  853. ; durch andere Daten ersetzen. Sollte die Länge der neuen Daten von der
  854. ; Länge der alten Daten abweichen, dann werden die nachfolgenden Daten im
  855. ; Puffer automatisch dementsprechend nach vorne oder hinten verschoben. Die
  856. ; aktuelle Cursorposition wird automatisch nachgeführt, und steht nach dem
  857. ; Aufruf dementsprechend auf dem ersten Byte hinter den neuen Daten.
  858. ;----------------------------------------------------------------------------
  859. ; Synopsis:    newPos = Replace (BufHandle, Data, Size, OldSize)
  860. ;               D0*                 A0       A1!   D0     D1
  861. ;
  862. ; Eingaben:    A0 --> APTR  auf den gewünschten BufHandle
  863. ;              A1 --> APTR  auf die neuen Daten
  864. ;              D0 --> ULONG Menge der neuen Daten in Bytes
  865. ;              D1 --> ULONG Menge der alten Daten in Bytes
  866. ;
  867. ; Ergebnis:    D0 --> LONG - die neue Cursorposition, wenn alles in Ordnung
  868. ;                             (ACHTUNG: Zählbeginn = 0 !!)
  869. ;                          - negativ, wenn Fehler (Info mit »LastError()«)
  870. ;
  871. ; Bemerkung:   Diese Funktion löscht automatisch die Prozessor-Caches.
  872. ;
  873. ; Siehe auch:  »SeekBuf()«, »Store()«, »InsertBuf()«, »InsertFile()«,
  874. ;              »Get()«, »Clear()«
  875. ;============================================================================
  876.  
  877. ;*** extra.library / Get()                   (OFFSET -132) V1.323 ***
  878. ;============================================================================
  879. ; Mit dieser Funktion können Sie sich die physische Adresse der aktuellen
  880. ; Cursorposition besorgen. Diese Adresse können Sie dann für andere Funk-
  881. ; tionen verwenden (z.B. »Text()« der graphics.library, um die Daten auszu-
  882. ; geben). Die Daten brauchen also für solche Anwendungen nicht extra noch
  883. ; einmal ausgelesen werden (wär' ja auch unsinnig).
  884. ;----------------------------------------------------------------------------
  885. ; Synopsis:    address = Get (BufHandle)
  886. ;                D0*             A0
  887. ;
  888. ; Eingaben:    A0 --> APTR auf den gewünschten BufHandle
  889. ;
  890. ; Ergebnis:    D0 --> APTR - auf die Daten an der aktuellen Cursorposition
  891. ;                          - 0-PTR, wenn akt. Cursorposition = Pufferende
  892. ;                          - negativ, wenn Fehler (Info mit »LastError()«)
  893. ;
  894. ; Bemerkung:   Die gelieferte Adresse sollte NUR für lesende Zugriffe ver-
  895. ;              wendet werden, da alles was man »per Hand« an dieser Stelle
  896. ;              verändert nicht vom Puffersystem registriert wird.
  897. ;
  898. ;   ACHTUNG:   Die ermittelte Adresse wird mit Aufruf der nächsten Puffer-
  899. ;   ¯¯¯¯¯¯¯¯   funktion, welche Daten speichert od. löscht, wieder ungültig.
  900. ;              Eventuell worden die Daten dann nämlich verlagert.
  901. ;
  902. ; Siehe auch:  »SeekBuf()«, »Store()«, »InsertBuf()«, »InsertFile()«,
  903. ;              »Replace()«, »Clear()«
  904. ;============================================================================
  905.  
  906. ;*** extra.library / Clear()                 (OFFSET -138) V1.323 ***
  907. ;============================================================================
  908. ; Diese Funktion löscht die angegebene Anzahl Datenbytes ab der aktuellen
  909. ; Cursorposition in dem durch den BufHandle spezifizierten Puffer. Eventuell
  910. ; noch dahinter stehende Daten werden wieder nach vorne aufgerückt. Die ak-
  911. ; tuelle Cursorposition bleibt unverändert, da die nachfolgenden Daten, auf
  912. ; denen die aktuelle Position nach der Operation ja steht, wieder nach vorne
  913. ; auf die Position der ehemaligen Daten aufrücken.
  914. ;----------------------------------------------------------------------------
  915. ; Synopsis:    end = Clear (BufHandle, Size)
  916. ;              D0*             A0       D0
  917. ;
  918. ; Eingaben:    A0 --> APTR  auf den gewünschten BufHandle
  919. ;              D0 --> ULONG Anzahl der zu löschenden Datenbytes
  920. ;
  921. ; Ergebnis:    D0 --> BOOL - UPPER, wenn noch Daten aufgerückt sind
  922. ;                          - EQUAL, wenn Löschaktion Pufferende erreicht hat
  923. ;                          - LOWER, wenn Fehler (Info mit »LastError()«)
  924. ;
  925. ; Bemerkung:   Diese Funktion löscht automatisch die Prozessor-Caches.
  926. ;
  927. ; Siehe auch:  »SeekBuf()«, »Store()«, »InsertBuf()«, »InsertFile()«,
  928. ;              »Replace()«, »Get()«
  929. ;============================================================================
  930.  
  931. ;*** extra.library / FindData()              (OFFSET -144) V1.323 ***
  932. ;============================================================================
  933. ; Mit dieser Funktion können Sie bestimmte Datenabschnitte innerhalb eines
  934. ; Puffers suchen. Die Suche beginnt dabei an der aktuellen Cursorposition.
  935. ; Werden die Daten gefunden, dann wird die gefundene Position automatisch
  936. ; zur aktuellen Cursorposition, im anderen Falle bleibt die alte Cursorposi-
  937. ; tion erhalten. Im Zusammenspiel mit den anderen Find-Funktionen und der
  938. ; Funktion »Replace()« kann man so z.B. einfach eine Search/Replace-Schleife
  939. ; realisieren. Der anzugebende Schlüsselwert dient bei späteren Aufrufen von
  940. ; »FindNext()/FindPrev()« als Identifikation der gewünschten Daten, welche
  941. ; vorher mit dieser Funktion initialisiert wurden. Es sind max. 8 Schlüssel-
  942. ; werte pro Puffer möglich. Sie könnten die ersten 4 Schlüssel z.B. verwen-
  943. ; den, um nach SPACES, TABS, LF's und FF's zu suchen, womit Sie auf einfache
  944. ; Art u. Weise eine Funktion hätten, mit der Sie den Cursor Wort-, Zeilen-
  945. ; oder auch Seitenweise weiter- bzw. zurückschalten könnten.
  946. ;----------------------------------------------------------------------------
  947. ; Synopsis:    success = FindData (BufHandle, Key, Data, Size)
  948. ;                D0*                  A0      D0   A1!    D1
  949. ;
  950. ; Eingaben:    A0 --> APTR  auf den gewünschten BufHandle
  951. ;              D0 --> ULONG Kennungs-Schlüssel dieser Daten (0-7 !!)
  952. ;              A1 --> APTR  auf die zu suchenden Daten
  953. ;              D1 --> ULONG Länge der zu suchenden Daten in Byte
  954. ;
  955. ; Ergebnis:    D0 --> BOOL - UPPER, wenn die Daten gefunden wurden
  956. ;                          - EQUAL, wenn sie nicht gefunden wurden
  957. ;                          - LOWER, wenn Fehler (Info mit »LastError()«)
  958. ;
  959. ; Bemerkung:   Der Speicher Ihrer übergebenen Such-Daten kann nach Aufruf der
  960. ;              Funktion anderweitig weiterverwendet werden, da die Such-Daten
  961. ;              für die Verwendung mit den Funktionen »FindNext()/FindPrev()«
  962. ;              intern kopiert und zwischengespeichert werden. Wenn schon Daten
  963. ;              von einem früheren Aufruf dieser Funktion für den gleichen
  964. ;              Schlüssel vorhanden sind, dann werden diese freigegeben und die
  965. ;              jetzt angegebenen Daten an deren Stelle gespeichert.
  966. ;              Diese Funktion löscht automatisch die Prozessor-Caches.
  967. ;
  968. ; Siehe auch:  »FindNext()«, »FindPrev()«, »FreeFinds()«, »SetBookmark()«,
  969. ;              »GotoBookmark()«
  970. ;============================================================================
  971.  
  972. ;*** extra.library / FindNext()              (OFFSET -150) V1.323 ***
  973. ;============================================================================
  974. ; Diese Funktion sucht das nächste Auftreten der Daten eines vorangegangenen
  975. ; »FindData()«-Aufrufs. Die Suche beginnt wie bei o.g. Funktion wieder an der
  976. ; aktuellen Cursorposition. Mit dem Schlüssel geben Sie an, von welchen Daten
  977. ; das nächste Auftreten gesucht werden soll.
  978. ;----------------------------------------------------------------------------
  979. ; Synopsis:    success = FindNext (BufHandle, Key)
  980. ;                D0*                  A0      D0
  981. ;
  982. ; Eingaben:    A0 --> APTR  auf den gewünschten BufHandle
  983. ;              D0 --> ULONG Schlüsselwert der zu suchenden Daten (0-7 !!)
  984. ;
  985. ; Ergebnis:    D0 --> BOOL - UPPER, wenn die Daten gefunden wurden
  986. ;                          - EQUAL, wenn sie nicht gefunden wurden
  987. ;                          - LOWER, wenn Fehler (Info mit »LastError()«)
  988. ;
  989. ; Siehe auch:  »FindData()«, »FindPrev()«, »FreeFinds()«, »SetBookmark()«,
  990. ;              »GotoBookmark()«
  991. ;============================================================================
  992.  
  993. ;*** extra.library / FindPrev()              (OFFSET -156) V1.323 ***
  994. ;============================================================================
  995. ; Diese Funktion sucht das vorige Auftreten der Daten eines vorangegangenen
  996. ; »FindData()«-Aufrufs. Die Suche beginnt wie bei o.g. Funktion wieder an der
  997. ; aktuellen Cursorposition. Mit dem Schlüssel geben Sie an, von welchen Daten
  998. ; das vorhergehende Auftreten gesucht werden soll.
  999. ;----------------------------------------------------------------------------
  1000. ; Synopsis:    success = FindPrev (BufHandle, Key)
  1001. ;                D0*                  A0      D0
  1002. ;
  1003. ; Eingaben:    A0 --> APTR  auf den gewünschten BufHandle
  1004. ;              D0 --> ULONG Schlüsselwert der zu suchenden Daten (0-7 !!)
  1005. ;
  1006. ; Ergebnis:    D0 --> BOOL - UPPER, wenn die Daten gefunden wurden
  1007. ;                          - EQUAL, wenn sie nicht gefunden wurden
  1008. ;                          - LOWER, wenn Fehler (Info mit »LastError()«)
  1009. ;
  1010. ; Siehe auch:  »FindData()«, »FindNext()«, »FreeFinds()«, »SetBookmark()«,
  1011. ;              »GotoBookmark()«
  1012. ;============================================================================
  1013.  
  1014. ;*** extra.library / FreeFinds()             (OFFSET -162) V1.323 ***
  1015. ;============================================================================
  1016. ; Diese Funktion gibt die internen Kopien aller Such-Daten (alle vorhandenen
  1017. ; Schlüsselwerte) wieder frei. Dies kann manchmal sehr nützlich sein, wenn
  1018. ; Speichermangel besteht, und die Daten ohnehin nicht mehr benötigt werden.
  1019. ;----------------------------------------------------------------------------
  1020. ; Synopsis:    success = FreeFinds (BufHandle)
  1021. ;                D0*                   A0
  1022. ;
  1023. ; Eingaben:    A0 --> APTR auf den gewünschten BufHandle
  1024. ;
  1025. ; Ergebnis:    D0 --> BOOL - TRUE , wenn alles in Ordnung
  1026. ;                          - FALSE, wenn Fehler (Info mit »LastError()«)
  1027. ;
  1028. ; Bemerkung:   Nach Aufruf dieser Funktion müssen Sie erst wieder neue Daten
  1029. ;              via »FindData()« initialisieren, bevor Sie wieder die Funk-
  1030. ;              tionen für fortlaufendes bzw. rückläufiges Suchen verwenden
  1031. ;              können.
  1032. ;              Diese Funktion löscht automatisch die Prozessor-Caches.
  1033. ;
  1034. ; Siehe auch:  »FindData()«, »FindNext()«, »FindPrev()«, »SetBookmark()«,
  1035. ;              »GotoBookmark()«
  1036. ;============================================================================
  1037.  
  1038. ;*** extra.library / SetBookmark()           (OFFSET -168) V1.323 ***
  1039. ;============================================================================
  1040. ; Mit dieser Funktion erklären Sie die aktuelle Cursorposition zu einer
  1041. ; Bookmark. Diese Bookmarks (max. 16 pro Puffer) werden bei Speicher- oder
  1042. ; Löschoperationen im Puffer automatisch neuberechnet, und halten somit
  1043. ; immer die markierte Stelle im »Gedächtnis«.
  1044. ;----------------------------------------------------------------------------
  1045. ; Synopsis:    success = SetBookmark (BufHandle, Key)
  1046. ;                D0*                     A0      D0
  1047. ;
  1048. ; Eingaben:    A0 --> APTR  auf den gewünschten BufHandle
  1049. ;              D0 --> ULONG Nummer der zu setzenden Bookmark (0..15 !!)
  1050. ;
  1051. ; Ergebnis:    D0 --> BOOL - TRUE , wenn alles in Ordnung
  1052. ;                          - FALSE, wenn Fehler (Info mit »LastError()«)
  1053. ;
  1054. ; Bemerkung:   Beachten Sie, daß jede Bookmark nur einmal vergeben werden
  1055. ;              kann. Das heißt, wenn Sie eine Bookmark verwenden, die Sie
  1056. ;              schon früher gesetzt haben, dann wird diese jetzt mit der
  1057. ;              neuen Position überschrieben.
  1058. ;
  1059. ; Siehe auch:  »FindData()«, »FindNext()«, »FindPrev()«, »FreeFinds()«,
  1060. ;              »GotoBookmark()«
  1061. ;============================================================================
  1062.  
  1063. ;*** extra.library / GotoBookmark()          (OFFSET -174) V1.323 ***
  1064. ;============================================================================
  1065. ; Mit dieser Funktion rufen Sie eine vorher gesetzte Bookmark ab. Das heißt,
  1066. ; daß die aktuelle Cursorposition auf die in der Bookmark gespeicherten Po-
  1067. ; sition gesetzt wird. Dies funktioniert natürlich nur, wenn die Daten an be-
  1068. ; sagter Stelle noch existieren, d.h. sie noch nicht gelöscht wurden. Alter-
  1069. ; nativ zu dieser Funktion können Sie auch »SeekBuf()« verwenden.
  1070. ;----------------------------------------------------------------------------
  1071. ; Synopsis:    success = GotoBookmark (BufHandle, Key)
  1072. ;                D0*                      A0      D0
  1073. ;
  1074. ; Eingaben:    A0 --> APTR  auf den gewünschten BufHandle
  1075. ;              D0 --> ULONG Nummer der gewünschten Bookmark (0..15 !!)
  1076. ;
  1077. ; Ergebnis:    D0 --> BOOL - TRUE , wenn alles in Ordnung
  1078. ;                          - FALSE, wenn Fehler (Info mit »LastError()«)
  1079. ;
  1080. ; Bemerkung:   Sollte diese Funktion fehlschlagen, dann bleibt die alte
  1081. ;              Cursorposition erhalten.
  1082. ;
  1083. ; Siehe auch:  »SeekBuf()«, »FindData()«, »FindNext()«, »FindPrev()«,
  1084. ;              »FreeFinds()«, »SetBookmark()«
  1085. ;============================================================================
  1086.  
  1087. ;*** extra.library / FindString()            (OFFSET -180) V1.323 ***
  1088. ;============================================================================
  1089. ; Diese Funktion sucht eine Bytefolge innerhalb einer anderen Bytefolge. Die
  1090. ; Suche findet dabei »Case-Sensitiv« statt, das heißt, »A« ist ungleich »a«.
  1091. ; Der verwendete Suchalgorithmus arbeitet mit »3-Phase-PreCheck«, womit so-
  1092. ; gar auf alten 68000er-Amigas noch ein Datendurchsatz von ca. 130 KByte/Sec
  1093. ; erreicht werden kann (je nach Auslastung des Multitaskings).
  1094. ;----------------------------------------------------------------------------
  1095. ; Synopsis:    position = FindString (Source, SourceLen, Find, FindLen)
  1096. ;                 D0*                   A0!      D0      A1!     D1
  1097. ;
  1098. ; Eingaben:    A0 --> STRPTR auf Adresse der zu durchsuchenden Bytefolge
  1099. ;              D0 --> ULONG  Länge der zu durchsuchenden Folge in Byte
  1100. ;              A1 --> STRPTR auf Adresse der zu suchenden Bytefolge
  1101. ;              D1 --> ULONG  Länge der zu suchenden Folge in Byte
  1102. ;
  1103. ; Ergebnis:    D0 --> LONG - die Position, ab welchem Byte der durchsuchten
  1104. ;                            Bytefolge die Gesuchte in ihr enthalten ist
  1105. ;                             (ACHTUNG: Zählbeginn = 1 !!)
  1106. ;                          - ist NULL, wenn die gesuchte Bytefolge nicht in
  1107. ;                            der Durchsuchten enthalten ist
  1108. ;                          - ist negativ, wenn ein Fehler aufgetreten ist
  1109. ;                            (Find-String länger als Source-String)
  1110. ;
  1111. ; Bemerkung:   Ich habe die Zeiger auf die Bytefolgen als STRPTR deklariert,
  1112. ;              da man diese Funktion wohl meistens für die Suche innerhalb
  1113. ;              von alphanumerischen Zeichenketten benutzen wird. Die Funktion
  1114. ;              kann aber genausogut zum Suchen von nicht druckbaren Zeichen
  1115. ;              benutzt werden, d.h. sie bricht ihre Arbeit nicht etwa beim
  1116. ;              Auftauchen eines 0-Bytes o.ä. ab. Um dies deutlich zu machen,
  1117. ;              rede ich hier auch absichtlich immerzu nur von »Bytefolgen«,
  1118. ;              und nicht etwa von »Strings« oder »Zeichenketten«.
  1119. ;
  1120. ; Siehe auch:  »GetLength()«
  1121. ;============================================================================
  1122.  
  1123. ;*** extra.library / GetLength()             (OFFSET -186) V1.323 ***
  1124. ;============================================================================
  1125. ; Diese Funktion ermittelt die Länge einer Bytefolge, welche mit dem spezi-
  1126. ; fizierten Byte abgeschlossen ist. Man kann so z.B. die Länge eines 0-ter-
  1127. ; minierten Strings ermitteln oder in Textpuffern die Linefeeds suchen und
  1128. ; somit die Länge einer Zeile ermitteln etc..
  1129. ;----------------------------------------------------------------------------
  1130. ; Synopsis:    length = GetLength (Start, EndByte, MaxBytes)
  1131. ;                D0*                A0!      D0       D1
  1132. ;
  1133. ; Eingaben:    A0 --> STRPTR auf die Startadresse der Bytefolge
  1134. ;              D0 --> UBYTE  zu suchendes EndByte (0-255)
  1135. ;              D1 --> ULONG  max. zu prüfende Byteanzahl (s. Bemerkung)
  1136. ;
  1137. ; Ergebnis:    D0 --> LONG - Länge der Bytefolge (ohne EndByte)
  1138. ;                          - negativ, wenn innerhalb eines angegebenen Be-
  1139. ;                            reichs kein EndByte gefunden wurde
  1140. ;
  1141. ; Bemerkung:   Der Parameter »MaxBytes« ist ein Grenzwert. Wird er erreicht,
  1142. ;              dann wird die Prüfung der Bytefolge abgebrochen. Dies erweist
  1143. ;              sich als nützlich, wenn innerhalb eines Puffers gesucht wird,
  1144. ;              dieser jedoch nicht überschritten werden soll, wenn bis zu
  1145. ;              dessen Ende kein EndByte gefunden wurde. Soll jedoch wirklich
  1146. ;              bis zum Auftauchen des Endwertes gesucht werden, dann geben
  1147. ;              Sie für diesen Parameter einfach -1 an.
  1148. ;               Ich habe den Zeiger auf die Bytefolge als STRPTR deklariert,
  1149. ;              da man diese Funktion wohl meistens für die Längenbestimmung
  1150. ;              von alphanumerischen Zeichenketten benutzen wird. Die Funktion
  1151. ;              kann aber genausogut zur Längenbestimmung eines Datenpuffers
  1152. ;              benutzt werden, d.h. sie bricht ihre Arbeit nicht etwa beim
  1153. ;              Auftauchen eines 0-Bytes o.ä. ab (es sei denn, dieses Byte ist
  1154. ;              als »EndByte« spezifiziert). Um dies deutlich zu machen, rede
  1155. ;              ich hier auch absichtlich immerzu nur von einer »Bytefolge«,
  1156. ;              und nicht etwa von einem »String« oder einer »Zeichenkette«.
  1157. ;
  1158. ; Siehe auch:  »FindString()«
  1159. ;============================================================================
  1160.  
  1161. ;*** extra.library / LastError()             (OFFSET -192) V1.323 ***
  1162. ;============================================================================
  1163. ; Ähnlich der Funktion »IoErr()« der dos.library ermittelt diese Funktion
  1164. ; die Nummer des zuletzt aufgetretenen »extra.library«-Fehlers innerhalb des
  1165. ; jeweiligen Tasks, der diese Funktion aufruft.
  1166. ;----------------------------------------------------------------------------
  1167. ; Synopsis:    error = LastError (VOID)
  1168. ;               D0
  1169. ;
  1170. ; Ergebnis:    D0 --> ULONG Fehlernummer (s. extradefs.i)
  1171. ;============================================================================
  1172.  
  1173. ;*** extra.library / LongToString()          (OFFSET -198) V1.323 ***
  1174. ;============================================================================
  1175. ; Mit dieser Funktion können Sie eine 32-Bit-Binärzahl (LONG) in einen druck-
  1176. ; baren Dezimalstring umwandeln. Die Zahl wird dabei entweder als vorzeichen-
  1177. ; los od. vorzeichenbehaftet interpretiert. Der String wird mit einem 0-Byte
  1178. ; abgeschlossen. Als Ergebnis erhalten Sie den Adress-Zeiger auf den String.
  1179. ;----------------------------------------------------------------------------
  1180. ; Synopsis:    string = LongToString (Value, Flag)
  1181. ;                D0                    D0     D1
  1182. ;
  1183. ; Eingaben:    D0 --> LONG die umzuwandelnde Zahl
  1184. ;              D1 --> BOOL - TRUE  -> vorzeichenbehaftet
  1185. ;                          - FALSE -> vorzeichenlos
  1186. ;
  1187. ; Ergebnis:    D0 --> STRPTR auf den generierten Dezimalstring(+0)
  1188. ;
  1189. ; Bemerkung:   Sie brauchen sich nicht um die Beschaffung bzw. Freigabe des
  1190. ;              Stringpuffers zu kümmern, da der benötigte Speicherplatz Ihrem
  1191. ;              Task beim Öffnen der »extra.library« zur Verfügung gestellt
  1192. ;              wird, und dann beim Schließen der Library auch automatisch
  1193. ;              wieder freigegeben wird. Beachten Sie jedoch, daß der Puffer
  1194. ;              aufgrund dieser Verwaltungsmethode beim jeweils nächsten Auf-
  1195. ;              ruf dieser Funktion wieder überschrieben wird.
  1196. ;
  1197. ;   ACHTUNG:   Benutzen Sie IMMER den Rückgelieferten Wert als Startadresse
  1198. ;   ¯¯¯¯¯¯¯¯   zum Auslesen des Strings. Der Puffer hat zwar seine feste Po-
  1199. ;              sition, aber da der String rechtsbündig in diesem liegt, und
  1200. ;              der String selbst ja bei jedem Aufruf eine andere Länge haben
  1201. ;              kann, ändert sich damit natürlich auch die logischer Weise
  1202. ;              links liegende Startadresse.
  1203. ;
  1204. ; Siehe auch:  »StringToLong()«
  1205. ;
  1206. ;----------------------------------------------------------------------------
  1207. ;--- Veränderungen seit v3.342 ----------------------------------------------
  1208. ;----------------------------------------------------------------------------
  1209. ;
  1210. ; Bemerkung:   Diese Funktion ist veraltet, bitte benutzen Sie stattdessen
  1211. ;              die Funktion »Int32ToString()«.
  1212. ;
  1213. ;   ACHTUNG:   Diese Funktion bleibt aus kompatiblitätsgründen nach wie vor
  1214. ;   ¯¯¯¯¯¯¯¯   unverändert wie oben beschrieben erhalten und funktionsfähig.
  1215. ;
  1216. ; Siehe auch:  »Int64ToString()«, »FFPToString()«,
  1217. ;              »SGLToString()«, »DBLToString()«, »StringToInt32()«
  1218. ;============================================================================
  1219.  
  1220. ;*** extra.library / StringToLong()          (OFFSET -204) V1.323 ***
  1221. ;============================================================================
  1222. ; Diese Funktion wandelt einen Dezimalstring, soweit möglich, in eine 32-Bit-
  1223. ; Binärzahl (LONG) um. Der Dezimalstring darf außer den Ziffern 0-9 an füh-
  1224. ; render Stelle auch ein Minus-/Pluszeichen bzw. ein Plusminuszeichen bei der
  1225. ; Zahl Null, sowie an beliebiger Stelle einen Dezimalpunkt enthalten.
  1226. ; Die Umwandlung erfolgt immer Vorzeichenbehaftet.
  1227. ;----------------------------------------------------------------------------
  1228. ; Synopsis:    value = StringToLong (DezString, Len)
  1229. ;               D0                      A0      D0
  1230. ;
  1231. ; Eingaben:    A0 --> STRPTR auf den umzuwandelnden Dezimalstring
  1232. ;                             (-2147483648 bis 2147483647)
  1233. ;              D0 --> ULONG  die Länge des Dezimalstrings
  1234. ;
  1235. ; Ergebnis:    D0 --> LONG die durch den String repräsentierte 32-Bit-Zahl
  1236. ;
  1237. ; Bemerkung:   Wenn Sie einen Dezimalpunkt im String angeben, dann wird nur
  1238. ;              der Vorkommawert (INTEGER) umgewandelt.
  1239. ;
  1240. ;   ACHTUNG:   Da das Ergebnis ja stets jeden beliebigen Wert annehmen kann,
  1241. ;   ¯¯¯¯¯¯¯¯   ist es nicht möglich, eine generelle Fehlermeldung Über das
  1242. ;              Rückgabe-Register auszugeben. Wenn Sie also nicht garantieren
  1243. ;              können, daß es sich um einen auswertbaren Dezimalstring
  1244. ;              handelte, dann sollten Sie im Anschluß an diese Funktion immer
  1245. ;              »LastError()« aufrufen, um festzustellen, ob das Ergebnis
  1246. ;              gültig ist, oder ob ein Fehler auftrat. (s.a. extradefs.i)
  1247. ;
  1248. ; Siehe auch:  »LongToString()«
  1249. ;
  1250. ;----------------------------------------------------------------------------
  1251. ;--- Veränderungen seit v3.342 ----------------------------------------------
  1252. ;----------------------------------------------------------------------------
  1253. ;
  1254. ; Bemerkung:   Diese Funktion ist veraltet, bitte benutzen Sie stattdessen
  1255. ;              die Funktion »StringToInt32()«.
  1256. ;
  1257. ;   ACHTUNG:   Diese Funktion bleibt aus kompatiblitätsgründen nach wie vor
  1258. ;   ¯¯¯¯¯¯¯¯   unverändert wie oben beschrieben erhalten und funktionsfähig.
  1259. ;
  1260. ; Siehe auch:  »Int32ToString()«, »Int64ToString()«, »FFPToString()«,
  1261. ;              »SGLToString()«, »DBLToString()«
  1262. ;============================================================================
  1263.  
  1264. ;*** extra.library / PackByteRun1()          (OFFSET -210) V1.323 ***
  1265. ;============================================================================
  1266. ; Diese Funktion führt an dem übergebenen Datenbereich eine cmpByteRun1-
  1267. ; Kompression durch. Dies ist die Standardmethode, mit der IFF-ILBM-Grafiken
  1268. ; komprimiert werden. Für andere Daten als Grafiken ist diese Methode auch
  1269. ; wenig geeignet, und wird bei solchen daher auch kaum Ersparnis bringen.
  1270. ;----------------------------------------------------------------------------
  1271. ; Synopsis:    outLen = PackByteRun1 (InBuf, InLen, OutBuf, OutLen)
  1272. ;               D0*                    A0!     D0    A1!     D1!
  1273. ;
  1274. ; Eingaben:    A0 --> APTR  auf die Quelldaten (zu komprimierende Daten)
  1275. ;              D0 --> ULONG Anzahl zu verarbeitender Bytes der Quelldaten
  1276. ;              A1 --> APTR  auf den Ausgabepuffer für die komprimierten Daten
  1277. ;              D1 --> ULONG Größe des Ausgabepuffers in Byte
  1278. ;
  1279. ; Ergebnis:    D0 --> LONG - Anzahl der geschriebenen Bytes im Ausgabepuffer
  1280. ;                          - negativ, wenn Ausgabepuffer zu klein
  1281. ;
  1282. ; Siehe auch:  »UnpackByteRun1()«
  1283. ;============================================================================
  1284.  
  1285. ;*** extra.library / UnpackByteRun1()        (OFFSET -216) V1.323 ***
  1286. ;============================================================================
  1287. ; Diese Funktion ist das Gegenstück zu »PackByteRun1()«. Sie entpackt die
  1288. ; von o.g. Funktion komprimierten Daten wieder zurück ins Originalformat.
  1289. ;----------------------------------------------------------------------------
  1290. ; Synopsis:    count = UnpackByteRun1 (InParam, OutBuf, OutLen)
  1291. ;               D0                      A0!      A1!      D0
  1292. ;
  1293. ; Eingaben:    A0 --> APTR  auf eine UnpackParam-Struktur (s. extradefs.i)
  1294. ;              A1 --> APTR  auf den Ausgabepuffer für die entpackten Daten
  1295. ;              D0 --> ULONG Größe des Ausgabepuffers in Bytes (= Anzahl zu
  1296. ;                           entpackender Bytes)
  1297. ;
  1298. ; Ergebnis:    D0 --> ULONG Anzahl tatsächlich entpackter Bytes, ist dieser
  1299. ;                           Wert kleiner als die gewünschte Anzahl, dann sind
  1300. ;                           alle Daten entpackt.
  1301. ;
  1302. ; Bemerkung:   Die Parameter-Struktur muß jeweils beim ersten Aufruf für ei-
  1303. ;              nen gepackten Datenblock initialisiert werden, und dient dann
  1304. ;              bei weiteren Aufrufen als Kennung des jeweiligen Datenblocks.
  1305. ;              Auf diese Weise können Sie einen größeren Datenblock in mehre-
  1306. ;              ren kleinen Einheiten wieder entpacken. Sie brauchen dann nur
  1307. ;              immer den Ausgabepuffer und dessen Größe neu angeben und die-
  1308. ;              selbe Struktur verwenden, bis alle Daten entpackt sind.
  1309. ;              Diese Funktion löscht automatisch die Prozessor-Caches.
  1310. ;
  1311. ;   ACHTUNG:   In C/C++ ist die A0-APTR-Eingabe als Typ STRUCT *UnpackParam
  1312. ;   ¯¯¯¯¯¯¯¯   zu behandeln.
  1313. ;
  1314. ; Siehe auch:  »PackByteRun1()«
  1315. ;============================================================================
  1316.  
  1317. ;*** extra.library / PrintIoError()          (OFFSET -222) V1.323 ***
  1318. ;============================================================================
  1319. ; Ist bei einer DOS-Operation ein Fehler aufgetreten, dann rufen Sie die
  1320. ; Funktion »IoErr()« der dos.library auf. Anschließend, wenn Sie eventuell
  1321. ; schon eine Fehlerbearbeitung vorgenommen haben, können Sie die Fehler-
  1322. ; nummer an diese Funktion weiterleiten. Es wird die verbale Fehlermeldung
  1323. ; zu dieser Nummer ermittelt, und dann die ganze Sache ordentlich mittels
  1324. ; »ShowMsg()« präsentiert. Sie brauchen dann nur noch darauf zu reagieren,
  1325. ; ob der Anwender einen nochmaligen Versuch wünscht oder nicht.
  1326. ;----------------------------------------------------------------------------
  1327. ; Synopsis:    button = PrintIoError (DOSErrNum)
  1328. ;                D0*                     D0
  1329. ;
  1330. ; Eingaben:    D0 --> ULONG ein beliebiger positiver Wert (meist ein DOS-Error)
  1331. ;
  1332. ; Ergebnis:    D0 --> BOOL - UPPER, wenn RETRY (linke Maustaste gedrückt,
  1333. ;                                   od. L-ALT, od. L-AMIGA, od. beide L-Tasten)
  1334. ;                          - EQUAL, wenn ABORT (rechte Maustaste)
  1335. ;                                   od. R-ALT, od. R-AMIGA, od. beide R-Tasten)
  1336. ;                          - LOWER, wenn Fehler (Info mit »LastError()«)
  1337. ;
  1338. ; Bemerkung:   Wenn der angegebene Wert keine bekannte Fehlernummer ist, so
  1339. ;              wird die Meldung »UNKNOWN_ERROR_NUMBER« verwendet.
  1340. ;============================================================================
  1341.  
  1342. ;*** extra.library / FlipCase()              (OFFSET -228) V1.323 ***
  1343. ;============================================================================
  1344. ; Diese Funktion wandelt alle Kleinbuchstaben des angegebenen Strings in ihre
  1345. ; entsprechenden Großbuchstaben um, oder umgekehrt. Bei dieser Operation wer-
  1346. ; den auch Umlaute und internationale Sonderzeichen korrekt berücksichtigt,
  1347. ; sofern diese im normalen ASCII-Code, und nicht in Latin-Codesets o.ä. ver-
  1348. ; korksten Standards vorliegen.
  1349. ;----------------------------------------------------------------------------
  1350. ; Synopsis:    VOID FlipCase (String, Len, Flag)
  1351. ;                              A0!    D0    D1
  1352. ;
  1353. ; Eingaben:    A0 --> STRPTR auf den umzuwandelnden String
  1354. ;              D0 --> ULONG  die Länge des Strings
  1355. ;              D1 --> BOOL - TRUE  für klein -> groß
  1356. ;                          - FALSE für groß  -> klein
  1357. ;============================================================================
  1358.  
  1359. ;*** extra.library / CmpMem()                (OFFSET -234) V1.323 ***
  1360. ;============================================================================
  1361. ; Diese Funktion vergleicht zwei Speicherbereiche miteinander. Es wird auto-
  1362. ; matisch die schnellste Methode für den Vergleich gewählt.
  1363. ;----------------------------------------------------------------------------
  1364. ; Synopsis:    result = CmpMem (BlockA, BlockB, Size)
  1365. ;                D0*              A0      A1     D0
  1366. ;
  1367. ; Eingaben:    A0 --> APTR  auf die Startadresse von Bereich #1
  1368. ;              A1 --> APTR  auf die Startadresse von Bereich #2
  1369. ;              D0 --> ULONG Anzahl der zu prüfenden Bytes
  1370. ;
  1371. ; Ergebnis:    D0 --> ULONG - ist NULL, wenn die Bereiche identisch sind
  1372. ;                           - die Position der ersten Abweichung, wenn nicht
  1373. ;                             identisch (ACHTUNG: Zählbeginn = 1 !!)
  1374. ;============================================================================
  1375.  
  1376. ;*** extra.library / CopyMemI()              (OFFSET -240) V1.323 ***
  1377. ;============================================================================
  1378. ; Hierbei handelt es sich um eine intelligente Speicher-Kopierfunktion.
  1379. ; Intelligent in sofern, als daß sie automatisch erkennt, ob sich der Quell-
  1380. ; und der Zielbereich an irgendeiner Stelle überlappen. Ist dies der Fall,
  1381. ; wird ermittelt, ob mit aufwärts oder abwärts zählenden Adressen kopiert
  1382. ; werden muß, um ein überschreiben von noch nicht kopierten Quellabschnitten
  1383. ; zu vermeiden. Es wird der schnellste Weg für den Kopiervorgang gewählt.
  1384. ;----------------------------------------------------------------------------
  1385. ; Synopsis:    VOID CopyMemI (Source, Dest, Size)
  1386. ;                               A0    A1!    D0
  1387. ;
  1388. ; Eingaben:    A0 --> APTR  auf die Startadresse des Quell-Datenbereichs
  1389. ;              A1 --> APTR  auf die Startadresse des Ziel-Datenbereichs
  1390. ;              D0 --> ULONG Anzahl der zu kopierenden Bytes
  1391. ;
  1392. ; Bemerkung:   Diese Funktion löscht automatisch die Prozessor-Caches.
  1393. ;============================================================================
  1394.  
  1395. ;*** extra.library / FillMem()               (OFFSET -246) V1.323 ***
  1396. ;============================================================================
  1397. ; Diese Funktion füllt den angegebenen Speicherbereich mit dem spezifizierten
  1398. ; Wert. Anhand der Größe des Wertes wird ermittelt, ob eine Byte-, Wort- oder
  1399. ; Langwort-Füllung durchgeführt werden muß. Es wird der schnellste Weg für
  1400. ; die Füllung gewählt. Der Füllwert wird immer als Vorzeichenlos betrachtet.
  1401. ;----------------------------------------------------------------------------
  1402. ; Synopsis:    success = FillMem (Start, Size, Value)
  1403. ;                D0*               A0!    D0    D1
  1404. ;
  1405. ; Eingaben:    A0 --> APTR  auf den zu füllenden Bereich
  1406. ;                            (ACHTUNG: gerade Adresse bei WORD/LONG-Füllung)
  1407. ;              D0 --> ULONG Größe des Bereichs in Bytes !!
  1408. ;              D1 --> ULONG Füllwert (BYTE: 0-255, WORD: >255, LONG: >65535)
  1409. ;
  1410. ; Ergebnis:    D0 --> BOOL - TRUE , wenn alles in Ordnung
  1411. ;                          - FALSE, wenn Fehler (Info mit »LastError()«)
  1412. ;
  1413. ; Bemerkung:   Bei Wort- und Langwort-Modus wird die Größe auf das nächste
  1414. ;              Vielfache von 2 bzw. 4 abgerundet, um so eine Bereichsüber-
  1415. ;              schreitung zu vermeiden. Achten Sie darauf, daß der Bereich
  1416. ;              mindestens so groß ist, um einen Wert aufzunehmen, anderen-
  1417. ;              falls wird aufgrund der Abrundung keine Füllung durchgeführt.
  1418. ;              Diese Funktion löscht automatisch die Prozessor-Caches.
  1419. ;============================================================================
  1420.  
  1421. ;*** extra.library / GetMem()                (OFFSET -252) V1.323 ***
  1422. ;============================================================================
  1423. ; Diese Funktion belegt Speicher via »AllocMem()« der exec.library, bindet
  1424. ; aber zusätzlich sämtliche Bereiche in die Speicherliste der Task-Struktur
  1425. ; des aufrufenden Tasks ein. Somit wird verhindert, daß der Speicherplatz bis
  1426. ; zum nächsten Reset blockiert bleibt, wenn vergessen wurde, diesen wieder
  1427. ; freizugeben, bevor das Programm beendet wurde. In diesem Falle wird der be-
  1428. ; legte Speicherplatz automatisch wieder freigegeben, wenn der Task aus dem
  1429. ; System entfernt wird.
  1430. ;----------------------------------------------------------------------------
  1431. ; Synopsis:    address = GetMem (Size, Requirements)
  1432. ;                D0*              D0         D1
  1433. ;
  1434. ; Eingaben:    D0 --> ULONG die Größe des gewünschten Bereichs in Byte
  1435. ;              D1 --> ULONG die Eigenschaften des gewünschten Bereichs
  1436. ;
  1437. ; Ergebnis:    D0 --> APTR - auf die Adresse des belegten Bereichs
  1438. ;                          - 0-PTR, wenn die gewünschte Speicherart bzw.
  1439. ;                            Größe nicht verfügbar ist
  1440. ;
  1441. ; Bemerkung:   Der Wert MEMF_CLEAR zum Löschen des belegten Bereichs wird
  1442. ;              intern mit den Requirements verknüpft und braucht somit nicht
  1443. ;              explizit angegeben werden.
  1444. ;
  1445. ; Siehe auch:  »UnGetMem()«
  1446. ;============================================================================
  1447.  
  1448. ;*** extra.library / UnGetMem()              (OFFSET -258) V1.323 ***
  1449. ;============================================================================
  1450. ; Diese Funktion ist das Gegenstück zu »GetMem()«. Sie gibt entweder den an-
  1451. ; gegebenen Speicherblock oder alle Blöcke, welche mittels der o.g. Funktion
  1452. ; für den aufrufenden Task belegt wurden, wieder frei.
  1453. ;----------------------------------------------------------------------------
  1454. ; Synopsis:    VOID UnGetMem (Block)
  1455. ;                              A0
  1456. ;
  1457. ; Eingaben:    A0 --> APTR - die Adresse eines Speicherblocks von »GetMem()«
  1458. ;                          - ein 0-PTR gibt alle Speicherblöcke frei
  1459. ;
  1460. ; Siehe auch:  »GetMem()«
  1461. ;
  1462. ;----------------------------------------------------------------------------
  1463. ;--- Veränderungen seit v3.342 ----------------------------------------------
  1464. ;----------------------------------------------------------------------------
  1465. ;
  1466. ; Bemerkung:   Ab sofort erweitert sich die o.g. Funktionalität auch auf die
  1467. ;              Speicherblöcke von »GetMem16()«. Das heißt, man kann einzelne
  1468. ;              »GetMem16()«-Blöcke mittels dieser Funktion wieder freigeben,
  1469. ;              und beim Freigeben aller Speicherblöcke schließt das jetzt die
  1470. ;              Speicherblöcke von »GetMem16()« mit ein.
  1471. ;
  1472. ; Siehe auch:  »GetMem16()«
  1473. ;============================================================================
  1474.  
  1475. ;*** extra.library / OutlineOff()            (OFFSET -264) V1.323 ***
  1476. ;============================================================================
  1477. ; Diese Funktion schaltet den AreaOutline-Mode des angegebenen RastPorts aus.
  1478. ;----------------------------------------------------------------------------
  1479. ; Synopsis:    VOID OutlineOff (RastPort)
  1480. ;                                 A0!
  1481. ;
  1482. ; Eingaben:    A0 --> APTR auf eine gültige RastPort-Struktur
  1483. ;
  1484. ;   ACHTUNG:   In C/C++ ist die A0-APTR-Eingabe als Typ STRUCT *RastPort
  1485. ;   ¯¯¯¯¯¯¯¯   zu behandeln.
  1486. ;
  1487. ; Siehe auch:  »OutlineOn()«, »SetOPen()«
  1488. ;============================================================================
  1489.  
  1490. ;*** extra.library / OutlineOn()             (OFFSET -270) V1.323 ***
  1491. ;============================================================================
  1492. ; Diese Funktion schaltet den AreaOutline-Mode des angegebenen RastPorts ein.
  1493. ;----------------------------------------------------------------------------
  1494. ; Synopsis:    VOID OutlineOn (RastPort)
  1495. ;                                A0!
  1496. ;
  1497. ; Eingaben:    A0 --> APTR auf eine gültige RastPort-Struktur
  1498. ;
  1499. ;   ACHTUNG:   In C/C++ ist die A0-APTR-Eingabe als Typ STRUCT *RastPort
  1500. ;   ¯¯¯¯¯¯¯¯   zu behandeln.
  1501. ;
  1502. ; Siehe auch:  »OutlineOff()«, »SetOPen()«
  1503. ;============================================================================
  1504.  
  1505. ;*** extra.library / SetOPen()               (OFFSET -276) V1.323 ***
  1506. ;============================================================================
  1507. ; Diese Funktion setzt den für die Area-Outlines zu benutzenden Farbstift.
  1508. ;----------------------------------------------------------------------------
  1509. ; Synopsis:    VOID SetOPen (RastPort, Pen)
  1510. ;                              A0!     D0!
  1511. ;
  1512. ; Eingaben:    A0 --> APTR  auf eine gültige RastPort-Struktur
  1513. ;              D0 --> UBYTE Nummer des zu verwendenden Farbstiftes
  1514. ;
  1515. ;   ACHTUNG:   Diese Funktion schaltet den AreaOutline-Modus automatisch
  1516. ;   ¯¯¯¯¯¯¯¯   ein, wenn er noch nicht aktiv sein sollte !!
  1517. ;               In C/C++ ist die A0-APTR-Eingabe als Typ STRUCT *RastPort
  1518. ;              zu behandeln.
  1519. ;
  1520. ; Siehe auch:  »OutlineOff()«, »OutlineOn()«
  1521. ;============================================================================
  1522.  
  1523. ;*** extra.library / SpecText()              (OFFSET -282) V1.323 ***
  1524. ;============================================================================
  1525. ; Diese Funktion arbeitet wie »Text()« der graphics.library, nur wird hier
  1526. ; um den Text eine Umrandung gezeichnet, wodurch Sie bei entsprechender Farb-
  1527. ; wahl u.a. Schatten-, Outline- od. Reliefeffekte erzeugen können. Durch
  1528. ; Flags haben Sie auch die Möglichkeit z.B. die aktuellen Farben eines Rast-
  1529. ; ports zu verwenden, was es ermöglicht die Farben in höheren Programmier-
  1530. ; sprachen einfach durch Verwendung der COLOR-Befehle solcher Sprachen ein-
  1531. ; zustellen bzw. zu verändern. Ein weiterer Unterschied zu der Gfx-Funktion
  1532. ; ist der, daß sich die X/Y-Positionen hier auf die linke obere Ecke be-
  1533. ; ziehen, und nicht wie bei »Text()« auf die Baseline des verwendeten Fonts.
  1534. ;----------------------------------------------------------------------------
  1535. ; Synopsis:    success = SpecText (RastPort, String, xPos, yPos)
  1536. ;                D0*                 A0!      A1!    D0!    D1!
  1537. ;
  1538. ; Eingaben:    A0 --> APTR   auf eine gültige RastPort-Struktur
  1539. ;              A1 --> STRPTR auf den auszugebenden Text(+0)
  1540. ;              D0 --> UWORD  die X-Koordinate, wo der Text erscheinen soll
  1541. ;              D1 --> UWORD  die Y-Koordinate, wo der Text erscheinen soll
  1542. ;
  1543. ; Ergebnis:    D0 --> BOOL - TRUE , wenn alles funktioniert hat
  1544. ;                          - FALSE, wenn zu wenig Speicher für benötigte
  1545. ;                                   IntuiText-Strukturen
  1546. ;
  1547. ; Bemerkung:   Bevor Sie diese Funktion aufrufen sollten Sie mit der Funk-
  1548. ;              tion »SpecTextPrefs()« einstellen, wie diese Funktion arbei-
  1549. ;              ten soll. Wenn keine Einstellungen vorgenommen wurden, dann
  1550. ;              werden folgende Defaults benutzt: MPen=0, TLPen=2, BRPen=1,
  1551. ;              Style=STS_Plain, Maske=STM_Outline und Flags=STF_AP2MP. Die
  1552. ;              Einstellungen des angegebenen RastPorts werden durch diese
  1553. ;              Funktion NICHT verändert.
  1554. ;
  1555. ;   ACHTUNG:   Wenn der angegebene RastPort der eines Intuition-Windows ist,
  1556. ;   ¯¯¯¯¯¯¯¯   dann werden zu lange Texte am Rand autom. abgeschnitten. Han-
  1557. ;              delt es sich jedoch um einen selbst eingerichteten RastPort
  1558. ;              der nicht über einen Layer verfügt, dann haben Sie die Verant-
  1559. ;              wortung sicherzustellen, daß der Rand keinesfalls überschrie-
  1560. ;              ben wird (X/Y u. Textlänge beachten). Anderenfalls könnte es
  1561. ;              zu einem Systemabsturtz mit Datenverlust kommen, für den ich
  1562. ;              KEINERLEI HAFTUNG übernehme !!
  1563. ;               In C/C++ ist die A0-APTR-Eingabe als Typ STRUCT *RastPort
  1564. ;              zu behandeln.
  1565. ;
  1566. ; Siehe auch:  »SpecTextPrefs()«
  1567. ;============================================================================
  1568.  
  1569. ;*** extra.library / SpecTextPrefs()         (OFFSET -288) V1.323 ***
  1570. ;============================================================================
  1571. ; Mit dieser Funktion bestimmen Sie, wie die Funktion »SpecText()« dieser
  1572. ; Library arbeiten soll. Die Einstellungen gelten nur für den aufrufenden
  1573. ; Task, jeder Task kann also seine eigenen Prefs verwenden, ohne daß sie
  1574. ; sich gegenseitig in die Quere kommen. (möchte ja wohl auch sein, oder ??)
  1575. ;----------------------------------------------------------------------------
  1576. ; Synopsis:    VOID SpecTextPrefs (MPen, TLPen, BRPen, Style, Mask, Flags)
  1577. ;                                  D0!    D1!    D2!    D3!   D4!    D5!
  1578. ;
  1579. ; Eingaben:    D0 --> UBYTE Nr. der gewünschten Schriftfarbe (MainPen)
  1580. ;              D1 --> UBYTE Nr. der Farbe für ob./li.-Umrandung (TopLeftPen)
  1581. ;              D2 --> UBYTE Nr. der Farbe für un./re.-Ränder (BottomRightPen)
  1582. ;              D3 --> UBYTE der zu verwendende SoftStyle (s.extradefs.i)
  1583. ;              D4 --> UBYTE eine Maske, die angibt welche Umrandungsteile tat-
  1584. ;                           sächlich gezeichnet werden sollen (s. Bemerkung)
  1585. ;              D5 --> UWORD zusätzliche Spezifikationen (s. extradefs.i)
  1586. ;
  1587. ; Bemerkung:   Wenn die Flags »STF_AP2MP«, »STF_BP2TL« bzw. »STF_OP2BR« an-
  1588. ;              gegeben werden, dann werden die Parameter »MPen«, »TLPen« und
  1589. ;              »BRPen« deshalb NICHT ignoriert, vielmehr werden sie vermerkt
  1590. ;              und kommen zur Anwendung, wenn durch eine Änderung der Flags
  1591. ;              die o.g. Flags nicht mehr länger existent sind. In der Maske
  1592. ;              bedeutet jedes gesetzte Bit, daß der entsprechende Teil der
  1593. ;              Umrandung gezeichnet wird. Einige vordefinierte Werte finden
  1594. ;              Sie in dem Includefile »extradefs.i«
  1595. ;
  1596. ;              Die Maske hat folgendes Format:
  1597. ;              Bit-Nr. |  7 |  6 |  5 |  4 |  3 |  2 |  1 |  0 
  1598. ;              --------+----+----+----+----+----+----+----+----
  1599. ;              Randpos.| TL |  T | TR |  R | BR |  B | BL |  L
  1600. ;
  1601. ;              TL=oben/links,   T=oben,  TR=oben/rechts, R=rechts,
  1602. ;              BR=unten/rechts, B=unten, BL=unten/links, L=links
  1603. ;
  1604. ;   ACHTUNG:   Wenn Sie keine Flags zur Uebernahme von nur einzelnen Kompo-
  1605. ;   ¯¯¯¯¯¯¯¯   nenten verwenden, dann werden alle Werte übernommen.
  1606. ;
  1607. ; Siehe auch:  »SpecText()«
  1608. ;============================================================================
  1609.  
  1610. ;*** extra.library / ShowMsg()               (OFFSET -294) V1.323 ***
  1611. ;============================================================================
  1612. ; Diese Funktion stellt eine Alternative zu der Routine »DisplayAlert()« der
  1613. ; intuition.library dar. Diese Funktion arbeitet grundsätzlich genauso wie
  1614. ; die Intuition-Routine, bietet aber bei der Gestaltung des Alert-Textes noch
  1615. ; die Möglichkeit, Schriftfarbe und Schriftstil Ihren Wünschen entsprechend
  1616. ; zu wählen. Außerdem paßt sich diese Funktion ab OS 2.0 automatisch an die
  1617. ; aktuellen »overscan.prefs« an, und landet so nicht, wie ihrer großen Intu-
  1618. ; ition-Schwester schon öfter passiert, außerhalb der Bildröhre ?!
  1619. ;----------------------------------------------------------------------------
  1620. ; Synopsis:    button = ShowMsg (Param, Type, Height, ColorTab)
  1621. ;                D0*              A0!   D0!     D1       D2!
  1622. ;
  1623. ; Eingaben:    A0 --> STRPTR auf den Parameter-String (s. Bemerkung)
  1624. ;              D0 --> LONG   Alert-Typ, hiervon ist nur das MSB interessant:
  1625. ;                             MSB (Bit 31) gesetzt DeadEnd, sonst Recovery
  1626. ;                            Nach einem DeadEnd-Alert folgt ein System-Reset.
  1627. ;              D1 --> ULONG  die Höhe des Alerts in Videozeilen (max. 200)
  1628. ;              D2 --> APTR - auf eine optionale Farbtabelle (s. Bemerkung)
  1629. ;                          - 0-PTR zur Verwendung der Standardfarben
  1630. ;
  1631. ; Ergebnis:    D0 --> BOOL - UPPER, wenn linke Maustaste gedrückt wurde,
  1632. ;                                   od. L-ALT, od. L-AMIGA, od. beide L-Tasten
  1633. ;                          - EQUAL, wenn rechte Maustaste gedrückt wurde,
  1634. ;                                   od. R-ALT, od. R-AMIGA, od. beide R-Tasten
  1635. ;                          - LOWER, Fehler (genaue Info mit »LastError()«)
  1636. ;
  1637. ; Bemerkung:   Wenn Ihnen die Standardfarben nicht recht sind, dann können
  1638. ;              Sie sie durch die Angabe einer Farbtabelle folgenden Formats
  1639. ;              auf die von Ihnen gewünschten Werte ändern. Für alle Farben,
  1640. ;              für die kein Eintrag in der Tabelle existiert, werden weiter-
  1641. ;              hin die Standardfarben benutzt. Die Farbanteile können jeweils
  1642. ;              Werte von 0-15 annehmen. Assembler-Programmierer können zur
  1643. ;              einfacheren Erstellung der Tabelle das Macro »SMCOLOR()« aus
  1644. ;              dem Includefile »extradefs.i« verwenden.
  1645. ;               Für BASIC u. C/C++ sind hierfür ähnliche Funktionen bzw.
  1646. ;              Macros in den entsprechenden Includefiles definiert. Bitte
  1647. ;              entnehmen Sie die Beschreibung jener Macros bitte direkt aus
  1648. ;              den entsprechenden Includefiles.
  1649. ;
  1650. ;              Aufbau der Farbtabelle:
  1651. ;         +-->   UBYTE Nr. der Farbe (3-15)(0-2 werden ignoriert)
  1652. ;         |    + UWORD Rotanteil*256 + Grünanteil*16 + Blauanteil
  1653. ;         |    + UBYTE folgt ein weiterer Farbeintrag ?? (0=nein/1=ja)
  1654. ;         |
  1655. ;         |    wenn weiterer Farbeintrag=ja, dann --+
  1656. ;         |                                         |
  1657. ;         +-----------------------------------------+
  1658. ;
  1659. ;              Aufbau des Parameter-Stings:
  1660. ;         +-->   UWORD X-Koordinate dieses Teilstrings ----\ (jeweils bezogen
  1661. ;         |    + UBYTE Y-Koordinate dieses Teilstrings ----/ auf li./ob. Ecke)
  1662. ;         |    + UBYTE neue SpecTextPrefs ?? (0=nein/1=ja)
  1663. ;         |
  1664. ;         |    wenn SpecTextPrefs=ja, dann
  1665. ;         |      + UBYTE Nr. des für »SpecText()« zu verwendenden »MPen« \
  1666. ;         |      + UBYTE Nr. des zu verwendenden »TLPen«   ______________/
  1667. ;         |      + UBYTE Nr. des zu verwendenden »BRPen«  /    \  /
  1668. ;         |      + UBYTE der zu verwendende SoftStyle   _/      \/
  1669. ;         |      + UBYTE die zu verwendende Randmaske _/(s. »SpecTextPrefs()«)
  1670. ;         |    ansonsten folgt direkt
  1671. ;         |
  1672. ;         |    + TEXT  der auszugebende Text selbst mit abschließendem 0-Byte 
  1673. ;         |    + UBYTE folgt ein weiterer Teilstring ?? (0=nein/1=ja)
  1674. ;         |
  1675. ;         |    wenn weiterer Teilstring=ja, dann --+
  1676. ;         |                                        |
  1677. ;         +----------------------------------------+
  1678. ;
  1679. ;            - Zur einfacheren Erstellung des Parameter-Strings können
  1680. ;              Assembler-Programmierer die Macros »SMTEXTP()« u. »SMTEXT()«
  1681. ;              aus dem mitgelieferten Includefile »extradefs.i« verwenden.
  1682. ;               Für BASIC u. C/C++ sind hierfür ähnliche Funktionen bzw.
  1683. ;              Macros in den entsprechenden Includefiles definiert. Bitte
  1684. ;              entnehmen Sie die Beschreibung jener Macros bitte direkt aus
  1685. ;              den entsprechenden Includefiles.
  1686. ;
  1687. ;              Tabelle der vorhandenen Standardfarben:
  1688. ;               1 - hellgrau (nur für TLPen u. BRPen) 3 - rot(100%)
  1689. ;               4 - grün(100%)     5 - blau(100%)     6 - gelb(100%)
  1690. ;               7 - violett(100%)  8 - türkis(100%)   9 - weiß(100%)
  1691. ;              10 - weinrot       11 - orange        12 - pink
  1692. ;              13 - schilfgrün    14 - lila          15 - himmelblau
  1693. ;
  1694. ;              Die Farben 0-2 sind reserviert und werden automatisch in 3, 4
  1695. ;              bzw. 5 umgewandelt, falls sie angegeben werden. Nur für TLPen
  1696. ;              und BRPen ist zusätzlich auch Farbe 1 erlaubt. Als Styles und
  1697. ;              Masken gelten die gleichen, wie bei »SpecTextPrefs()«
  1698. ;
  1699. ;              Bis zum Auftauchen der ersten Prefs im Parameterstring werden
  1700. ;              folgende Defaults verwendet: MPen=7, alle anderen Einträge 0.
  1701. ;
  1702. ;              Die Erstellung des Textes erfolgt, wie Sie sicher schon er-
  1703. ;              raten haben, via »SpecText()« dieser Library. Allerdings wer-
  1704. ;              den die aktuellen Prefs Ihres Task zu genannter Funktion durch
  1705. ;              die hier angegebenen Prefs in keinster Weise verändert.
  1706. ;
  1707. ;   ACHTUNG:   Diese Funktion darf NUR von vollwertigen DOS-Prozessen auf-
  1708. ;   ¯¯¯¯¯¯¯¯   gerufen werden. Ein normaler EXEC-Task ist nicht ausreichend.
  1709. ;
  1710. ;              Nur OCS/ECS/AGA-Version:
  1711. ;              ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  1712. ;              Der von dieser Funktion benutzte RastPort hat KEINEN Layer,
  1713. ;              d.h. Sie müssen selbst aufpassen, daß die Texte innerhalb des
  1714. ;              RastPorts bleiben (640 x angegebene Höhe). Durch die Verwen-
  1715. ;              dung von 16 Farben benötigt diese Funktion gegenüber der In-
  1716. ;              tuition-Routine wesentlich mehr ChipRam (bei max. Höhe 64 KB).
  1717. ;              Sollte diese Menge nicht mehr verfügbar sein, so bricht diese
  1718. ;              Funktion mit einer entsprechenden Fehlermeldung ab.
  1719. ;
  1720. ;              Nur CGX-Version:
  1721. ;              ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  1722. ;              Bei der CGX-Version kann es vorkommen, das der Mauszeiger nach
  1723. ;              abschalten des Sprite-DMA (während der Anzeige der Message)
  1724. ;              weiterhin sichtbar bleibt. Das hängt davon ab, ob die GfxBase
  1725. ;              gültige SimpleSprite-Einträge für alle Hardware-Sprites hat.
  1726. ;              Wenn Sie grundsätzlich eine CGX-Workbench verwenden, und Ihr
  1727. ;              System hochfahren ohne vor Öffnung des WB-Screens irgendwelche
  1728. ;              Ausgaben durch die Startup-Sequenz zu tätigen, dann sind o.g.
  1729. ;              Einträge in der GfxBase immer uninitialisiert, und der Maus-
  1730. ;              zeiger bleibt demzufolge immer sichtbar. Um dies zu ändern, muß
  1731. ;              einfach mal ein normaler Amiga-Screen (PAL, NTSC, EURO36 etc.)
  1732. ;              geöffnet werden, was dazu führt, daß die Einträge initialisiert
  1733. ;              werden. Eine zweite Möglichkeit ist, einfach die ENV-Variable
  1734. ;              KEEPAMIGAVIDEO von CyberGraphX zu aktivieren.
  1735. ;
  1736. ; Siehe auch:  »SpecText()«, »SpecTextPrefs()«
  1737. ;============================================================================
  1738.  
  1739. ;*** String-Verwaltung ***
  1740. ;============================================================================
  1741. ; String-Aufbau und -Verwaltung der »extra.library«-Funktionen ab V3.342
  1742. ;
  1743. ; 1.Problem
  1744. ; ¯¯¯¯¯¯¯¯¯
  1745. ; Um die Speicherbelegung der Strings im Auge zu behalten legt die Library
  1746. ; intern für jeden zugreifenden Task eine EXEC-Liste an, in der alle erzeugten
  1747. ; Strings dieses Tasks gesammelt werden. Wenn der betreffende Task die Library
  1748. ; wieder schließt, dann werden automatisch alle Strings und damit alle dadurch
  1749. ; belegten Speicherresourcen wieder freigegeben. Es ist also praktisch un-
  1750. ; nötig, daß Ihr Programm jeden String selbst via »DiscardString()« wieder
  1751. ; freigibt. Wie auch immer, sollte eine Speichermangel-Situation auftreten,
  1752. ; dann können Sie selbstverständlich einen, einige od. alle Strings seperat
  1753. ; mit o.g. Funktion wieder freigeben, sofern Sie diese nicht mehr benötigen.
  1754. ;
  1755. ; 2.Problem
  1756. ; ¯¯¯¯¯¯¯¯¯
  1757. ; Es sollte möglichst Speicherplatzschonend gearbeitet werden. Nun ergibt sich
  1758. ; jedoch das Problem, daß man vorher nie so genau weiß wie lang ein String
  1759. ; einmal wird (besonders bei »VSPrintF()«). Die Library verwendet aus diesem
  1760. ; Grunde zunächst einmal einen Puffer, der dem 8-fachen der theoretisch max.
  1761. ; erreichbaren Länge entspricht. Anschließend, wenn der String generiert wurde,
  1762. ; dann wird dessen tatsächliche Länge ermittelt, und der Puffer entsprechend
  1763. ; angepasst. Sie können also davon ausgehen, daß nie mehr Speicher als unbe-
  1764. ; dingt notwendig durch die Strings belegt wird. Beachten Sie aber bitte auch,
  1765. ; das dieses Vorgehen keiner exakten Grundlage entspringt, denn auch wenn ein
  1766. ; 8-fach größerer Puffer am Anfang der Generierung wohl die meisten Fälle ab-
  1767. ; decken kann, so könnte doch irgendwann und -wo der exotische Fall auftreten,
  1768. ; daß diese Größe eben doch nicht ausreicht. Sollten Sie also irgendwelche
  1769. ; Probleme mit den String-Funktionen haben, welche auf einen zu kleinen Puffer
  1770. ; zurückzuführen sein könnten, dann teilen Sie mir dieses bitte mit, damit ich
  1771. ; mich um dieses Problem kümmern kann.
  1772. ;
  1773. ; 3.Problem
  1774. ; ¯¯¯¯¯¯¯¯¯
  1775. ; Gleichermaßen einfache Weiterverarbeitung der generierten Strings in ver-
  1776. ; schiedensten Programmiersprachen. So ist der rückgelieferte Zeiger einer der
  1777. ; String-Funktionen nicht einfach nur ein Zeiger auf einen 0-Byte-terminierten
  1778. ; String, was z.B. für C/C++ vollkommen zureichend wäre, sondern ein Zeiger
  1779. ; auf ein Struktur-Konstrukt, welches sich vom Zeiger aus auch ins negative
  1780. ; erstreckt, und u.a. die Länge des Strings (ohne 0-Byte) als LONG-Variable
  1781. ; bereithält, welche z.B. in Assembler direkt an andere Funktionen weiterge-
  1782. ; leitet werden kann. Eine BASIC-Funktion im Include-File »extra.bc« nutzt
  1783. ; dies, um den String in einen BASIC-String umzukopieren, womit dann sogar für
  1784. ; diese Sprache eine einfache Weiterverarbeitung der Strings gewährleistet ist.
  1785. ;
  1786. ; Der genaue Aufbau eines solchen Strings:
  1787. ; ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  1788. ;           (-16) APTR  Next   (nächster Eintrag der Liste)  (Finger weg !!)
  1789. ;           (-12) APTR  Prev   (voriger  Eintrag der Liste)  (Finger weg !!)
  1790. ;           ( -8) ULONG Alloc  (insgesamt belegter Speicher) (Finger weg !!)
  1791. ;           ------------------
  1792. ;           ( -4) ULONG Length (Länge des Strings ohne 0-Byte) (NUR LESEN !!)
  1793. ;           ------------------
  1794. ; Zeiger -> (  0) TEXT  String (hier beginnt der eigentliche String)
  1795. ;           (+??) UBYTE 0-Byte (hiermit endet der String)
  1796. ;
  1797. ; Die o.g. Informationen sind NICHT zum HACKEN gedacht, darum FINGER WEG !!
  1798. ; Ich garantiere lediglich für die Längenangabe, alle anderen negativen Ein-
  1799. ; träge können sich in neuen Versionen ohne Benachrichtigung ändern.
  1800. ;============================================================================
  1801.  
  1802. ;*** Ausgabe-Format-String ***
  1803. ;============================================================================
  1804. ; Aufbau des Ausgabe-Format-Strings zur Ausgabe formatierter Daten über die
  1805. ; Funktion »VSPrintF()« dieser Library:
  1806. ;
  1807. ; Jeder Format-String besteht aus beliebigen Zeichen, die unverändert über-
  1808. ; nommen werden, sowie beliebig vielen Formatkommandos, die jeweils zur Kon-
  1809. ; vertierung eines zugehörigen übergebenen Arguments (in der Reihenfolge des
  1810. ; Auftretens) dienen. Jedes Formatkommando hat den folgenden Aufbau:
  1811. ;
  1812. ;   %[flags][width[.limit]][size]type
  1813. ;
  1814. ;   Bestandteile in eckigen Klammern sind wahlfrei.
  1815. ;
  1816. ; Bestandteile:
  1817. ; ¯¯¯¯¯¯¯¯¯¯¯¯¯
  1818. ;   flags
  1819. ;     '-' zur Linksjustierung
  1820. ;     '+' zur Ausgabe auch eines positiven Vorzeichens bei Zahlen
  1821. ;     '0' zur Ausgabe führender Nullen bei Zahlen
  1822. ;     '#' zum Voranstellen von '0x' bei hexadezimalen und '0' bei oktalen
  1823. ;         Zahlen sowie Ausgeben abschließender Nullen, falls für Type 'g'
  1824. ;         oder 'G' angegeben wird.
  1825. ;
  1826. ;   width
  1827. ;     Feldbreite als dezimale Ziffernfolge oder '*'; in diesem Fall wird der
  1828. ;     Wert als Argument des Typs LONG an entsprechender Stelle übergeben.
  1829. ;
  1830. ;   limit
  1831. ;     Genauigkeit als dezimale Ziffernfolge oder '*'; in diesem Fall wird der
  1832. ;     Wert als Argument des Typs LONG an entsprechender Stelle übergeben,
  1833. ;     der Wert beschreibt die maximale Anzahl von Zeichen bei Ausgabe einer
  1834. ;     Zeichenkette, die minimale Anzahl von Ziffern einer ganzzahligen Ausgabe
  1835. ;     oder die Anzahl der Dezimalstellen einer Fließkommaausgabe.
  1836. ;
  1837. ;   size
  1838. ;     Größenangabe des übergebenen zugehörigen Arguments:
  1839. ;
  1840. ;     'h' oder 'l' für ein Argument der Größe 32-Bit (Typ LONG od. ULONG)
  1841. ;     'L' für ein Argument der Größe 64-Bit, wobei zuerst die unteren
  1842. ;         32-Bit, danach die oberen 32-Bit angegeben werden müssen. Der
  1843. ;         Typ ist VLONG (extra.lib) bzw. LONG LONG (C/C++)
  1844. ;
  1845. ;   type
  1846. ;     Typangabe (Interpretation) des Arguments:
  1847. ;
  1848. ;     'd' oder 'i' zur Ausgabe einer vorzeichenbehafteten Dezimalzahl, das
  1849. ;         zugehörige Argument ist vom Typ LONG
  1850. ;
  1851. ;     'o' zur Ausgabe einer vorzeichenlosen Oktalzahl, das zugehörige Argument
  1852. ;         ist vom Typ LONG oder ULONG
  1853. ;
  1854. ;     'x' zur Ausgabe einer vorzeichenlosen Hexadezimalzahl mit Kleinbuchstaben,
  1855. ;         das zugehörige Argument ist vom Typ LONG oder ULONG
  1856. ;
  1857. ;     'X' zur Ausgabe einer vorzeichenlosen Hexadezimalzahl mit Großbuchstaben,
  1858. ;         das zugehörige Argument ist vom Typ LONG oder ULONG
  1859. ;
  1860. ;     'u' zur Ausgabe einer vorzeichenlosen Dezimalzahl, das zugehörige Argument
  1861. ;         ist vom Typ ULONG
  1862. ;
  1863. ;     'c' zur Ausgabe eines Zeichens, das zugehörige Argument ist vom Typ LONG
  1864. ;         und wird in UBYTE (UCHAR) konvertiert
  1865. ;
  1866. ;     's' zur Ausgabe einer Zeichenkette, die mit einem Nullbyte abgeschlossen
  1867. ;         ist, das zugehörigen Argument ist vom Typ STRPTR (APTR)
  1868. ;
  1869. ;     'f' zur Ausgabe einer Fließkommazahl in nichtexponentieller Darstellung,
  1870. ;         das zugehörige Argument ist vom Typ DOUBLE
  1871. ;
  1872. ;     'e' zur Ausgabe einer Fließkommazahl in exponentieller Darstellung mit
  1873. ;         kleinem 'e', das zugehörige Argument ist vom Typ DOUBLE
  1874. ;
  1875. ;     'E' zur Ausgabe einer Fließkommazahl in exponentieller Darstellung mit
  1876. ;         großem 'E', das zugehörige Argument ist vom Typ DOUBLE
  1877. ;
  1878. ;     'g' zur Ausgabe einer Fließkommazahl je nach Exponent in nichtexpo-
  1879. ;         nentieller oder exponentieller Darstellung mit kleinem 'e', das zu-
  1880. ;         gehörige Argument ist vom Typ DOUBLE
  1881. ;
  1882. ;     'G' zur Ausgabe einer Fließkommazahl je nach Exponent in nichtexpo-
  1883. ;         nentieller oder exponentieller Darstellung mit großem 'E', das zu-
  1884. ;         gehörige Argument ist vom Typ DOUBLE
  1885. ;
  1886. ;     'p' zur Ausgabe einer hexadezimalen Speicheradresse, das zugehörige
  1887. ;         Argument ist vom Typ APTR (ULONG)
  1888. ;
  1889. ;     'n' zur Speicherung der Anzahl der bisher von diesem Funktionsaufruf
  1890. ;         ausgegebenen Zeichen in der LONG-Variablen, auf die das Argument vom
  1891. ;         Typ APTR zeigt dieses Argument wird nicht mit im Ausgabe-String
  1892. ;         ausgegeben, es bewirkt lediglich o.g. Speicherung
  1893. ;
  1894. ;     '%' zur Ausgabe eines Prozentzeichens
  1895. ;============================================================================
  1896.  
  1897. ;*** extra.library / VSPrintF()              (OFFSET -318) V3.342 ***
  1898. ;============================================================================
  1899. ; Diese Funktion benutzt einen vorgegebenen Format-String um die angegebenen
  1900. ; Argumente zu formatieren und als einen neuen formatierten String auszugeben.
  1901. ;----------------------------------------------------------------------------
  1902. ; Synopsis:    string = VSPrintF (FormString, Args)
  1903. ;                D0*                  A0!      A1!
  1904. ;
  1905. ; Eingaben:    A0 --> STRPTR auf den »Ausgabe-Format-String«(+0) (s.Bemerkung)
  1906. ;              A1 --> APTR   auf das 1. Element des Argumenten-Arrays, die Args
  1907. ;                            entsprechen in Reihenfolge und Größe dem Auftauchen
  1908. ;                            ihrer Platzhaltersymbole im Format-String
  1909. ;
  1910. ; Ergebnis:    D0 --> STRPTR - Zeiger auf den generierten Ausgabe-String(+0)
  1911. ;                            - 0-PTR, wenn kein Speicher für den String-Puffer
  1912. ;                              mehr frei war.
  1913. ;
  1914. ; Bemerkung:   Der von dieser Funktion generierte String bleibt solange gültig,
  1915. ;              wie Ihr Programm die »extra.library« geöffnet hält, es sei denn,
  1916. ;              Sie geben den String via »DiscardString()« vorzeitig frei.
  1917. ;               Weitere Informationen zum String-Handling der »extra.library«
  1918. ;              finden Sie im Abschnitt »String-Verwaltung«.
  1919. ;
  1920. ;              C/C++ Programmierer können auch die Funktion »VSPrintFArgs()«
  1921. ;              zur Angabe einer beliebigen Anzahl von Argumenten auf dem Stack
  1922. ;              verwenden, welche als Stub in der »rhosigma.lib« enthalten ist.
  1923. ;
  1924. ; Siehe auch:  »DiscardString()«
  1925. ;============================================================================
  1926.  
  1927. ;*** extra.library / GetMem16()              (OFFSET -324) V3.342 ***
  1928. ;============================================================================
  1929. ; Diese Funktion ist zum größten Teil äquivalent zu »GetMem()« dieser Library,
  1930. ; der Unterschied besteht darin, daß der Speicherblock hiermit auf einer durch
  1931. ; 16 teilbaren Adresse belegt wird, was speziell für Assembler-Programmierer
  1932. ; interessant ist, die die Daten mit dem MOVE16-Befehl einiger Prozessoren
  1933. ; verarbeiten wollen.
  1934. ;----------------------------------------------------------------------------
  1935. ; Synopsis:    address = GetMem16 (Size, Requirements)
  1936. ;                D0*                D0        D1
  1937. ;
  1938. ; Eingaben:    D0 --> ULONG die Größe des gewünschten Bereichs in Byte
  1939. ;              D1 --> ULONG die Eigenschaften des gewünschten Bereichs
  1940. ;
  1941. ; Ergebnis:    D0 --> APTR - auf die Adresse des belegten Bereichs
  1942. ;                          - 0-PTR, wenn die gewünschte Speicherart bzw.
  1943. ;                            Größe nicht verfügbar ist
  1944. ;
  1945. ; Bemerkung:   Der Wert MEMF_CLEAR zum Löschen des belegten Bereichs wird
  1946. ;              intern mit den Requirements verknüpft und braucht somit nicht
  1947. ;              explizit angegeben werden.
  1948. ;               Auch ein mit dieser Funktion belegter Speicherblock wird
  1949. ;              mittels der Funktion »UnGetMem()« freigegeben. Genauso werden
  1950. ;              beim freigeben aller Speicherblöcke von »GetMem()« jetzt auch
  1951. ;              zusätzlich alle »GetMem16()«-Blöcke freigegeben.
  1952. ;
  1953. ; Siehe auch:  »GetMem()«, »UnGetMem()«
  1954. ;============================================================================
  1955.  
  1956. ;*** extra.library / DiscardString()         (OFFSET -330) V3.342 ***
  1957. ;============================================================================
  1958. ; Diese Funktion gibt entweder den angegebenen String oder alle Strings, die
  1959. ; von den ...ToString-Funktionen (und von »VSPrintF()«) dieser Library für
  1960. ; den aufrufenden Task angelegt wurden, wieder frei.
  1961. ;----------------------------------------------------------------------------
  1962. ; Synopsis:    VOID DiscardString (MathString)
  1963. ;                                     A0
  1964. ;
  1965. ; Eingaben:    A0 --> STRPTR - die Adresse eines Strings von »VSPrintF()« oder
  1966. ;                              einer der anderen ...ToString-Funktionen, die ab
  1967. ;                              Version 3 der »extra.library« verfügbar sind
  1968. ;                            - ein 0-PTR gibt alle Strings frei
  1969. ;
  1970. ;   ACHTUNG:   Wenn ein Task die »extra.library« ENDGÜLTIG schließt (es kann
  1971. ;   ¯¯¯¯¯¯¯¯   ja sein, daß mehrere Open-Aufrufe verschachtelt wurden), dann
  1972. ;              werden automatisch alle Strings, die DIESER TASK belegt hatte
  1973. ;              (egal, mit welcher Funktion) wieder freigegeben.
  1974. ;
  1975. ; Siehe auch:  »Int32ToString()«, »Int64ToString()«, »FFPToString()«,
  1976. ;              »SGLToString()«, »DBLToString()«, »VSPrintF()«
  1977. ;============================================================================
  1978.  
  1979. ;*** extra.library / Int32ToString()         (OFFSET -336) V3.342 ***
  1980. ;============================================================================
  1981. ; Diese Funktion wandelt eine 32-Bit-Binärzahl (LONG) in einen druckbaren
  1982. ; String um. Dabei kann die Zahl sowohl als vorzeichenlos oder vorzeichenbe-
  1983. ; haftet interpretiert werden. Außerdem kann die Umwandlung mit Zahlenbasen
  1984. ; von 2-36 durchgeführt werden, um z.B. Hex- oder Octal-Strings zu erzeugen.
  1985. ;----------------------------------------------------------------------------
  1986. ; Synopsis:    string = Int32ToString (Value32Bit, Flag, Base)
  1987. ;                D0*                       D0       D2   D3!
  1988. ;
  1989. ; Eingaben:    D0 --> LONG  die umzuwandelnde 32-Bit-Binärzahl
  1990. ;              D2 --> BOOL  - TRUE , für vorzeichenbehaftete Umwandlung
  1991. ;                           - FALSE, für vorzeichenlose Umwandlung
  1992. ;              D3 --> UWORD die Zahlenbasis, welche zur Umrechnung benutzt
  1993. ;                           werden soll (2-36)
  1994. ;
  1995. ; Ergebnis:    D0 --> STRPTR - Zeiger auf den generierten String(+0)
  1996. ;                            - 0-PTR, wenn kein Speicher für den String-Puffer
  1997. ;                              mehr frei war.
  1998. ;
  1999. ; Bemerkung:   Der von dieser Funktion generierte String bleibt solange gültig,
  2000. ;              wie Ihr Programm die »extra.library« geöffnet hält, es sei denn,
  2001. ;              Sie geben den String via »DiscardString()« vorzeitig frei.
  2002. ;               Weitere Informationen zum String-Handling der »extra.library«
  2003. ;              finden Sie im Abschnitt »String-Verwaltung«.
  2004. ;
  2005. ; Siehe auch:  »Int64ToString()«, »FFPToString()«,
  2006. ;              »SGLToString()«, »DBLToString()«, »StringToInt32()«,
  2007. ;              »DiscardString()«
  2008. ;============================================================================
  2009.  
  2010. ;*** extra.library / Int64ToString()         (OFFSET -342) V3.342 ***
  2011. ;============================================================================
  2012. ; Diese Funktion wandelt eine 64-Bit-Binärzahl (VLONG) in einen druckbaren
  2013. ; String um. Dabei kann die Zahl sowohl als vorzeichenlos oder vorzeichenbe-
  2014. ; haftet interpretiert werden. Außerdem kann die Umwandlung mit Zahlenbasen
  2015. ; von 2-36 durchgeführt werden, um z.B. Hex- oder Octal-Strings zu erzeugen.
  2016. ;----------------------------------------------------------------------------
  2017. ; Synopsis:    string = Int64ToString (Lower32Bit, Upper32Bit, Flag, Base)
  2018. ;                D0*                       D0          D1       D2   D3!
  2019. ;
  2020. ; Eingaben:    D0 --> LONG  die unteren 32 Bit der umzuwandelnden 64-Bit-Binärzahl
  2021. ;              D1 --> LONG  die oberen  32 Bit der umzuwandelnden 64-Bit-Binärzahl
  2022. ;              D2 --> BOOL  - TRUE , für vorzeichenbehaftete Umwandlung
  2023. ;                           - FALSE, für vorzeichenlose Umwandlung
  2024. ;              D3 --> UWORD die Zahlenbasis, welche zur Umrechnung benutzt
  2025. ;                           werden soll (2-36)
  2026. ;
  2027. ; Ergebnis:    D0 --> STRPTR - Zeiger auf den generierten String(+0)
  2028. ;                            - 0-PTR, wenn kein Speicher für den String-Puffer
  2029. ;                              mehr frei war.
  2030. ;
  2031. ; Bemerkung:   Der von dieser Funktion generierte String bleibt solange gültig,
  2032. ;              wie Ihr Programm die »extra.library« geöffnet hält, es sei denn,
  2033. ;              Sie geben den String via »DiscardString()« vorzeitig frei.
  2034. ;               Weitere Informationen zum String-Handling der »extra.library«
  2035. ;              finden Sie im Abschnitt »String-Verwaltung«.
  2036. ;
  2037. ; Siehe auch:  »Int32ToString()«, »FFPToString()«,
  2038. ;              »SGLToString()«, »DBLToString()«, »StringToInt32()«,
  2039. ;              »DiscardString()«
  2040. ;============================================================================
  2041.  
  2042. ;*** extra.library / FFPToString()           (OFFSET -348) V3.342 ***
  2043. ;============================================================================
  2044. ; Diese Funktion wandelt eine binäre Fließkommazahl im Motorola-FFP-Format
  2045. ; (Fast Floating Point) (FFP=FLOAT) in einen druckbaren String um. Außerdem
  2046. ; kann die max. gewünschte Nachkommastellen-Anzahl angegeben werden.
  2047. ;----------------------------------------------------------------------------
  2048. ; Synopsis:    string = FFPToString (FFPValue, Digits)
  2049. ;                D0*                    D0       D3!
  2050. ;
  2051. ; Eingaben:    D0 --> FFP   die umzuwandelnde FFP-Fließkommazahl
  2052. ;              D3 --> UWORD - neg.: Exponential-Darstellung, Mantisse hat
  2053. ;                                   ABS(Wert)-1 Nachkommastellen
  2054. ;                           - null: Darstellung und Nachkommastellen automatisch,
  2055. ;                                   je nach Größe/Genauigkeit der FFP-Zahl
  2056. ;                           - pos.: Festkomma-Darstellung mit ABS(Wert) Nach-
  2057. ;                                   kommastellen
  2058. ;
  2059. ; Ergebnis:    D0 --> STRPTR - Zeiger auf den generierten String(+0)
  2060. ;                            - 0-PTR, wenn kein Speicher für den String-Puffer
  2061. ;                              mehr frei war.
  2062. ;
  2063. ; Bemerkung:   Der von dieser Funktion generierte String bleibt solange gültig,
  2064. ;              wie Ihr Programm die »extra.library« geöffnet hält, es sei denn,
  2065. ;              Sie geben den String via »DiscardString()« vorzeitig frei.
  2066. ;               Weitere Informationen zum String-Handling der »extra.library«
  2067. ;              finden Sie im Abschnitt »String-Verwaltung«.
  2068. ;
  2069. ; Siehe auch:  »Int32ToString()«, »Int64ToString()«,
  2070. ;              »SGLToString()«, »DBLToString()«, »StringToInt32()«,
  2071. ;              »DiscardString()«
  2072. ;============================================================================
  2073.  
  2074. ;*** extra.library / SGLToString()           (OFFSET -354) V3.342 ***
  2075. ;============================================================================
  2076. ; Diese Funktion wandelt eine binäre Fließkommazahl im IEEE 754 Single-Format
  2077. ; (Fließkommazahl einfacher Genauigkeit) (FLOAT) in einen druckbaren String um.
  2078. ; Außerdem kann die max. gewünschte Nachkommastellen-Anzahl angegeben werden.
  2079. ;----------------------------------------------------------------------------
  2080. ; Synopsis:    string = SGLToString (SGLValue, Digits)
  2081. ;                D0*                    D0       D3!
  2082. ;
  2083. ; Eingaben:    D0 --> FLOAT die umzuwandelnde Single-Fließkommazahl
  2084. ;              D3 --> UWORD - neg.: Exponential-Darstellung, Mantisse hat
  2085. ;                                   ABS(Wert)-1 Nachkommastellen
  2086. ;                           - null: Darstellung und Nachkommastellen automatisch,
  2087. ;                                   je nach Größe/Genauigkeit der SGL-Zahl
  2088. ;                           - pos.: Festkomma-Darstellung mit ABS(Wert) Nach-
  2089. ;                                   kommastellen
  2090. ;
  2091. ; Ergebnis:    D0 --> STRPTR - Zeiger auf den generierten String(+0)
  2092. ;                            - 0-PTR, wenn kein Speicher für den String-Puffer
  2093. ;                              mehr frei war.
  2094. ;
  2095. ; Bemerkung:   Der von dieser Funktion generierte String bleibt solange gültig,
  2096. ;              wie Ihr Programm die »extra.library« geöffnet hält, es sei denn,
  2097. ;              Sie geben den String via »DiscardString()« vorzeitig frei.
  2098. ;               Weitere Informationen zum String-Handling der »extra.library«
  2099. ;              finden Sie im Abschnitt »String-Verwaltung«.
  2100. ;
  2101. ; Siehe auch:  »Int32ToString()«, »Int64ToString()«, »FFPToString()«,
  2102. ;              »DBLToString()«, »StringToInt32()«,
  2103. ;              »DiscardString()«
  2104. ;============================================================================
  2105.  
  2106. ;*** extra.library / DBLToString()           (OFFSET -360) V3.342 ***
  2107. ;============================================================================
  2108. ; Diese Funktion wandelt eine binäre Fließkommazahl im IEEE 754 Double-Format
  2109. ; (Fließkommazahl doppelter Genauigkeit) (DOUBLE) in einen druckbaren String um.
  2110. ; Außerdem kann die max. gewünschte Nachkommastellen-Anzahl angegeben werden.
  2111. ;----------------------------------------------------------------------------
  2112. ; Synopsis:    string = DBLToString (Upper32Bit, Lower32Bit, Digits)
  2113. ;                D0*                     D0          D1        D3!
  2114. ;
  2115. ; Eingaben:    D0 --> LONG  die oberen  32 Bit der umzuwandelnden Double-Zahl
  2116. ;              D1 --> LONG  die unteren 32 Bit der umzuwandelnden Double-Zahl
  2117. ;              D3 --> UWORD - neg.: Exponential-Darstellung, Mantisse hat
  2118. ;                                   ABS(Wert)-1 Nachkommastellen
  2119. ;                           - null: Darstellung und Nachkommastellen automatisch,
  2120. ;                                   je nach Größe/Genauigkeit der DBL-Zahl
  2121. ;                           - pos.: Festkomma-Darstellung mit ABS(Wert) Nach-
  2122. ;                                   kommastellen
  2123. ;
  2124. ; Ergebnis:    D0 --> STRPTR - Zeiger auf den generierten String(+0)
  2125. ;                            - 0-PTR, wenn kein Speicher für den String-Puffer
  2126. ;                              mehr frei war.
  2127. ;
  2128. ; Bemerkung:   Der von dieser Funktion generierte String bleibt solange gültig,
  2129. ;              wie Ihr Programm die »extra.library« geöffnet hält, es sei denn,
  2130. ;              Sie geben den String via »DiscardString()« vorzeitig frei.
  2131. ;               Weitere Informationen zum String-Handling der »extra.library«
  2132. ;              finden Sie im Abschnitt »String-Verwaltung«.
  2133. ;
  2134. ; Siehe auch:  »Int32ToString()«, »Int64ToString()«, »FFPToString()«,
  2135. ;              »SGLToString()«, »StringToInt32()«,
  2136. ;              »DiscardString()«
  2137. ;============================================================================
  2138.  
  2139. ;*** extra.library / StringToInt32()         (OFFSET -366) V3.342 ***
  2140. ;============================================================================
  2141. ; Diese Funktion wandelt einen String, soweit möglich, in eine 32-Bit-Binär-
  2142. ; zahl (LONG) um. Der String darf außer den Ziffern 0-9, den Buchstaben aA-zZ,
  2143. ; an führender Stelle auch ein Minuszeichen sowie an beliebiger Stelle einen
  2144. ; Dezimalpunkt enthalten. Die Umwandlung erfolgt auf Wunsch vorzeichenbehaftet
  2145. ; oder vorzeichenlos mit der angegebenen Zahlenbasis.
  2146. ;----------------------------------------------------------------------------
  2147. ; Synopsis:    value = StringToInt32 (Int32String, Flag, Base)
  2148. ;               D0                        A0        D2   D3!
  2149. ;
  2150. ; Eingaben:    A0 --> STRPTR auf den umzuwandelnden String(+0)
  2151. ;              D2 --> BOOL   - TRUE , vorzeichenbehaftet umwandeln
  2152. ;                            - FALSE, vorzeichenlos umwandeln
  2153. ;              D3 --> UWORD  - 2-36: die Zahlenbasis, welche zur Umrechnung
  2154. ;                                    benutzt werden soll
  2155. ;                            - null: Zahlenbasis abhängig vom Präfix des
  2156. ;                                    Strings: '0x' od. '0X' = Basis 16
  2157. ;                                                      '0'  = Basis 8
  2158. ;                                                     sonst = Basis 10
  2159. ;
  2160. ; Ergebnis:    D0 --> LONG die durch den String repräsentierte 32-Bit-Zahl
  2161. ;
  2162. ; Bemerkung:   Wenn Sie einen Dezimalpunkt im String angeben, dann wird nur
  2163. ;              der Vorkommawert (INTEGER) umgewandelt.
  2164. ;
  2165. ;   ACHTUNG:   Da das Ergebnis ja stets jeden beliebigen Wert annehmen kann,
  2166. ;   ¯¯¯¯¯¯¯¯   ist es nicht möglich, eine generelle Fehlermeldung Über das
  2167. ;              Rückgabe-Register auszugeben. Wenn Sie also nicht garantieren
  2168. ;              können, daß es sich um einen auswertbaren Zahlenstring
  2169. ;              handelte, dann sollten Sie im Anschluß an diese Funktion immer
  2170. ;              »LastError()« aufrufen, um festzustellen, ob das Ergebnis
  2171. ;              gültig ist, oder ob ein Fehler auftrat. (s.a. extradefs.i)
  2172. ;              Dabei gelten die gleichen Fehlercodes wie bei »StringToLong()«.
  2173. ;
  2174. ; Siehe auch:  »Int32ToString()«, »Int64ToString()«, »FFPToString()«,
  2175. ;              »SGLToString()«, »DBLToString()«,
  2176. ;============================================================================
  2177.  
  2178. ;*** extra.library / SMCOLOR() ***
  2179. ;============================================================================
  2180. ; Dieses Macro erstellt einen Farbeintrag für die optional anzugebende Farb-
  2181. ; tabelle für die Funktion »ShowMsg()«.
  2182. ;----------------------------------------------------------------------------
  2183. ; Definiert:   extradefs.i  (Copyright © 1998-2004 RhoSigma, Roland Heyder)
  2184. ;
  2185. ; Schablone:   Pen/A/N, Red/A/N, Green/A/N, Blue/A/N, END/K/S
  2186. ;
  2187. ; Parameter:   Pen   --> Nr. des zu ändernden Farbstiftes (3-15)
  2188. ;                             (0-2 sind reserviert u. werden ignoriert)
  2189. ;
  2190. ;              Red   --> Rot-Anteil der neuen Farbe (0-15)
  2191. ;              Green --> Grün-Anteil der neuen Farbe (0-15)
  2192. ;              Blue  --> Blau-Anteil der neuen Farbe (0-15)
  2193. ;
  2194. ;              END   --> Wird dieses Schlüsselwort angegeben, dann endet die
  2195. ;                        Farbtabelle an dieser Stelle, anderenfalls muß ein
  2196. ;                        weiterer Farbeintrag (Macro-Aufruf) folgen.
  2197. ;
  2198. ; Bemerkung:   Ein Beispiel für die Benutzung dieses Macros finden Sie in der
  2199. ;              Datei »demo/ShowMsgDemo.ASM«.
  2200. ;
  2201. ; Siehe auch:  »SMTEXTP()«, »SMTEXT()«, »ShowMsg()«
  2202. ;============================================================================
  2203.  
  2204. ;*** extra.library / SMTEXTP() ***
  2205. ;============================================================================
  2206. ; Dieses Macro erstellt einen Teilstring des Parameterstrings der Funktion
  2207. ; »ShowMsg()« inclusive der gewünschten Einstellungen für die Textausgabe.
  2208. ; Wahlweise kann der Text automatisch zentriert, oder links- bzw. rechtsbündig
  2209. ; ausgerichtet werden.
  2210. ;----------------------------------------------------------------------------
  2211. ; Definiert:   extradefs.i  (Copyright © 1998-2004 RhoSigma, Roland Heyder)
  2212. ;
  2213. ; Schablone:   xPos/A/N, yPos/A/N, MPen/A/N, TLPen/A/N, BRPen/A/N, Style/A/N,
  2214. ;              Mask/A/N, Text/A, END/K/S
  2215. ;
  2216. ; Parameter:   xPos  --> x-Position des Textes,
  2217. ;                             oder einer der oben definierten SMTPOS-Werte
  2218. ;
  2219. ;              yPos  --> y-Position des Textes,
  2220. ;                             Ausrichtung erfolgt an der Oberkante des Fonts
  2221. ;
  2222. ;              MPen  --> gewünschter MainPen        \
  2223. ;              TLPen --> gewünschter TopLeftPen     |
  2224. ;              BRPen --> gewünschter BottomRightPen | (s. »SpecTextPrefs()«)
  2225. ;              Style --> gewünschter SoftStyle      |
  2226. ;              Mask  --> gewünschte  Randmaske      /
  2227. ;
  2228. ;              Text  --> der auszugebende Text selbst,
  2229. ;                             in <..>, wenn Leerzeichen enthalten sind
  2230. ;
  2231. ;              END   --> Wird dieses Schlüsselwort angegeben, dann endet der
  2232. ;                        Parameterstring an dieser Stelle, anderenfalls muß
  2233. ;                        ein weiterer Teilstring (Macro-Aufruf) folgen.
  2234. ;
  2235. ; Bemerkung:   Dieses Macro sollten Sie nur dann verwenden, wenn Sie für
  2236. ;              diesen Teilstring neue Einstellungen für Farben etc. machen
  2237. ;              wollen. Wenn dieser Teilstring jedoch mit den gleichen Ein-
  2238. ;              stellungen ausgegeben werden soll, wie der vorhergehende bzw.
  2239. ;              Sie die Default-Einstellungen verwenden wollen, dann müssen
  2240. ;              Sie stattdessen das Macro »SMTEXT()« verwenden.
  2241. ;
  2242. ;              Ein Beispiel für die Benutzung dieses Macros finden Sie in der
  2243. ;              Datei »demo/ShowMsgDemo.ASM«.
  2244. ;
  2245. ; Siehe auch:  »SMCOLOR()«, »SMTEXT()«, »ShowMsg()«
  2246. ;============================================================================
  2247.  
  2248. ;*** extra.library / SMTEXT() ***
  2249. ;============================================================================
  2250. ; Dieses Macro erstellt einen Teilstring des Parameterstrings der Funktion
  2251. ; »ShowMsg()«. Wahlweise kann der Text automatisch zentriert, oder links- bzw.
  2252. ; rechtsbündig ausgerichtet werden.
  2253. ;----------------------------------------------------------------------------
  2254. ; Definiert:   extradefs.i  (Copyright © 1998-2004 RhoSigma, Roland Heyder)
  2255. ;
  2256. ; Schablone:   xPos/A/N, yPos/A/N, Text/A, END/K/S
  2257. ;
  2258. ; Parameter:   xPos  --> x-Position des Textes,
  2259. ;                             oder einer der oben definierten SMTPOS-Werte
  2260. ;
  2261. ;              yPos  --> y-Position des Textes,
  2262. ;                             Ausrichtung erfolgt an der Oberkante des Fonts
  2263. ;
  2264. ;              Text  --> der auszugebende Text selbst,
  2265. ;                             in <..>, wenn Leerzeichen enthalten sind
  2266. ;
  2267. ;              END   --> Wird dieses Schlüsselwort angegeben, dann endet der
  2268. ;                        Parameterstring an dieser Stelle, anderenfalls muß
  2269. ;                        ein weiterer Teilstring (Macro-Aufruf) folgen.
  2270. ;
  2271. ; Bemerkung:   Dieses Macro sollten Sie nur dann verwenden, wenn Sie für
  2272. ;              diesen Teilstring die gleichen Einstellungen wie für den vor-
  2273. ;              hergehenden Teilstring verwenden wollen. Wenn dieser Teil-
  2274. ;              string jedoch neue Einstellungen für Farben etc. erhalten
  2275. ;              soll, dann müssen Sie stattdessen das Macro »SMTEXTP()« ver-
  2276. ;              wenden.
  2277. ;
  2278. ;              Ein Beispiel für die Benutzung dieses Macros finden Sie in der
  2279. ;              Datei »demo/ShowMsgDemo.ASM«.
  2280. ;
  2281. ; Siehe auch:  »SMCOLOR()«, »SMTEXTP()«, »ShowMsg()«
  2282. ;============================================================================
  2283.  
  2284. ;*** lvo / Lib-Call-Macro ***
  2285. ;============================================================================
  2286. ; Dieses Macro dient zum Aufruf einer Funktion aus der dazugehörigen Library.
  2287. ;  Dabei ist dieses Macro gegenüber den CALL-Macros des NDK jedoch so intelli-
  2288. ; gent, daß es erkennt, ob mit ihm auch wirklich eine Funktion der zugehörigen
  2289. ; Library aufgerufen wird. Damit wird vermieden, daß versehendlich z.B. eine
  2290. ; Funktion der exec.library mit dem Macro (und damit natürlich auch dem Zeiger)
  2291. ; der graphics.library aufgerufen werden kann, was höchstwahrscheinlich sofort
  2292. ; einen Systemabsturz nach sich ziehen würde.
  2293. ;  Außerdem haben Optimal-Programmierer auch die Möglichkeit Quick-Aufrufe zu
  2294. ; verwenden, um jedes überflüssige Byte einzusparen. Für die Programmierung re-
  2295. ; entranter Programme ist ebenfalls eine Syntax definiert, bei der die voll-
  2296. ; ständige effektive Addresse des Basis-Zeigers als Parameter übergeben werden
  2297. ; muß, da dort ja keine flüchtigen absoluten Adressen verwendet werden dürfen.
  2298. ;----------------------------------------------------------------------------
  2299. ; Definiert:   ... _lib.i  (Copyright © 1998-2004 RhoSigma, Roland Heyder)
  2300. ;
  2301. ; Schablone:   Func/A, Opts/F/S
  2302. ;
  2303. ; Parameter:   Func --> Name der aufzurufenden Funktion ohne »_LVO_LIBNAME_«
  2304. ;
  2305. ;              Opts --> - das Schlüsselwort »OK« für einen QuickJump-Aufruf
  2306. ;                         (s. Bemerkung)
  2307. ;
  2308. ;                       - Opts weglassen, um Basis-Symbol »_LibnameBase« ins
  2309. ;                         Register A6 zu laden
  2310. ;
  2311. ;                       - die effektive Adresse, welche die Basis der Library
  2312. ;                         enthält (z.B. »globals_Libname(a5)«)
  2313. ;
  2314. ; Bemerkung:   Wird das Schlüsselwort »OK« angegeben, dann wird davon ausge-
  2315. ;              gangen, daß die richtige Basisadresse der Library bereits im
  2316. ;              Register A6 steht, und es wird sofort in die Funktion gesprungen.
  2317. ;============================================================================
  2318.  
  2319. /*** rhosigma / C-Stubs für »extra.library« Funktionen ***
  2320. *»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»
  2321. * Zusätzlich zu den unten angegebenen Funktionen enthält die »rhosigma.lib«
  2322. * auch die C-Stub-Routinen für alle »extra.library« Funktionen bis zu deren
  2323. * jeweils aktueller Version.
  2324. *  Diese befähigen Sie, die Funktionen der »extra.library« zu benutzen, auch
  2325. * wenn Ihr verwendeter ANSI-C/C++ Compiler nicht die Amigaspeziefische Ein-
  2326. * bindung dieser Funktionen über »#pragma amicall« bzw. »#pragma libcall«
  2327. * unterstützt.
  2328. *«««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««*/
  2329.  
  2330. /*** rhosigma / GetIOReq()                      V1.286 ***
  2331. *»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»
  2332. * Diese Funktion belegt und initialisiert einen neuen IORequest, welcher dann
  2333. * zur Kommunikation mit Devices verwendet werden kann.
  2334. *  Da diese Routine universell einsetzbar sein soll, wird jedoch nur ein APTR
  2335. * auf eine beliebige Struktur zurückgegeben, die man dann »casten« kann.
  2336. *-----------------------------------------------------------------------------
  2337. * Synopsis:     IOReq = GetIOReq (Size)
  2338. *
  2339. * Eingaben:     Size    --> (UWORD) Größe des benötigten IORequests in Byte.
  2340. *
  2341. * Ergebnis:     IOReq   --> (APTR) Zeiger auf den neuen IORequest oder NULL,
  2342. *                                  wenn der Request nicht belegt werden konnte.
  2343. *
  2344. * Bemerkung:    Die Ursache für das Fehlschlagen dieser Funktion ist entweder
  2345. *               Speichermangel, oder es war kein Signal-Bit für den Reply-Port
  2346. *               des IORequests mehr frei.
  2347. *
  2348. * Siehe auch:   »CopyIOReq()«, »FreeIOReq()«
  2349. *«««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««*/
  2350.  
  2351. /*** rhosigma / CopyIOReq()                     V1.286 ***
  2352. *»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»
  2353. * Diese Funktion legt eine Kopie von einem IORequest an, damit man z.B. für
  2354. * Lese- und Schreibzugriffe einen seperaten Request zur Verfügung hat.
  2355. *  Da diese Routine universell einsetzbar sein soll, wird jedoch nur ein APTR
  2356. * auf eine beliebige Struktur zurückgegeben, die man dann »casten« kann.
  2357. *-----------------------------------------------------------------------------
  2358. * Synopsis:     CopyReq = CopyIOReq(OrigReq)
  2359. *
  2360. * Eingaben:     OrigReq --> (APTR) Zeiger auf einen über »exec/OpenDevice()« be-
  2361. *                                  reits vollständig initialisierten IORequest.
  2362. *
  2363. * Ergebnis:     CopyReq --> (APTR) Zeiger auf den neuen IORequest oder NULL,
  2364. *                                  wenn der Request nicht belegt werden konnte.
  2365. *
  2366. * Bemerkung:    Die Ursache für das Fehlschlagen dieser Funktion ist entweder
  2367. *               Speichermangel, oder es war kein Signal-Bit für den Reply-Port
  2368. *               des IORequests mehr frei.
  2369. *                Der mit dieser Funktion erstellte IORequest muß, wenn er nicht
  2370. *               mehr benötigt wird, ebenfalls mit »FreeIOReq()« wieder freige-
  2371. *               geben werden.
  2372. *
  2373. *   ACHTUNG:    Sie dürfen niemals einen kopierten IORequest bei einen Aufruf
  2374. *   ¯¯¯¯¯¯¯¯    der Funktion »exec/CloseDevice()« verwenden. Benutzen Sie zu
  2375. *               diesem Zwecke immer den originalen IORequest, mit dem Sie auch
  2376. *               die Funktion »exec/OpenDevice()« aufgerufen haben.
  2377. *
  2378. * Siehe auch:   »GetIOReq()«, »FreeIOReq()«
  2379. *«««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««*/
  2380.  
  2381. /*** rhosigma / FreeIOReq()                     V1.286 ***
  2382. *»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»
  2383. * Diese Funktion gibt einen IORequest und alle damit verbundenen Resourcen
  2384. * wieder an das System zurück.
  2385. *-----------------------------------------------------------------------------
  2386. * Synopsis:     VOID FreeIOReq (IOReq)
  2387. *
  2388. * Eingaben:     IOReq   --> (APTR) Zeiger auf den freizugebenden IORequest.
  2389. *
  2390. *   ACHTUNG:    Diese Funktion darf nur für IORequests aufgerufen werden, die
  2391. *   ¯¯¯¯¯¯¯¯    entweder direkt mit der Funktion »GetIOReq()«, oder indirekt
  2392. *               über die Funktion »CopyIOReq()« erstellt worden sind.
  2393. *
  2394. * Siehe auch:   »GetIOReq()«, »CopyIOReq()«
  2395. *«««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««*/
  2396.  
  2397. /*** rhosigma / DoCMD()                         V1.286 ***
  2398. *»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»
  2399. * Diese Funktion initialisiert den IORequest mit dem angegbenen Kommando
  2400. * und sendet dieses dann im synchronen IO-Modus an das Device.
  2401. *-----------------------------------------------------------------------------
  2402. * Synopsis:     Error = DoCMD (IOReq, Comm)
  2403. *
  2404. * Eingaben:     IOReq   --> (APTR)  Zeiger auf den IORequest des anzusprechen-
  2405. *                                   den Devices.
  2406. *               Comm    --> (UWORD) Auszuführendes Device-Kommando.
  2407. *
  2408. * Ergebnis:     Error   --> (BYTE) Ist NULL, wenn alles in Ordnung, sonst eine
  2409. *                                  Fehlernummer des angesprochenen Devices
  2410. *                                  (s.a. Device-Includes).
  2411. *
  2412. * Siehe auch:   »SendCMD()«, »WaitCMD()«
  2413. *«««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««*/
  2414.  
  2415. /*** rhosigma / SendCMD()                       V1.286 ***
  2416. *»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»
  2417. * Diese Funktion initialisiert den IORequest mit dem angegbenen Kommando
  2418. * und sendet dieses dann im asynchronen IO-Modus an das Device.
  2419. *-----------------------------------------------------------------------------
  2420. * Synopsis:     VOID SendCMD (IOReq, Comm)
  2421. *
  2422. * Eingaben:     IOReq   --> (APTR)  Zeiger auf den IORequest des anzusprechen-
  2423. *                                   den Devices.
  2424. *               Comm    --> (UWORD) Auszuführendes Device-Kommando.
  2425. *
  2426. * Bemerkung:    Da diese Funktion nicht auf die Beendigung des IO-Vorgangs
  2427. *               wartet, kann sie natürlich auch keine Auskunft über Erfolg oder
  2428. *               Fehlschlag des selbigen geben. Sie sollten daher, wenn Sie mit
  2429. *               den anderen Dingen, welche Sie asynchron nebenherlaufen lassen
  2430. *               haben, fertig sind, die Funktion »WaitCMD()« aufrufen, welche
  2431. *               sowohl die eventuelle Fehlernummer liefert, sowie die erforder-
  2432. *               lichen Abschlußarbeiten erledigt.
  2433. *
  2434. * Siehe auch:   »DoCMD()«, »WaitCMD()«
  2435. *«««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««*/
  2436.  
  2437. /*** rhosigma / WaitCMD()                       V1.286 ***
  2438. *»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»
  2439. * Diese Funktion wartet auf die Beendigung eines zuvor mittels »SendCMD()« ge-
  2440. * starteten asynchronen IO-Vorgangs.
  2441. *-----------------------------------------------------------------------------
  2442. * Synopsis:     Error = WaitCMD (IOReq)
  2443. *
  2444. * Eingaben:     IOReq   --> (APTR) Zeiger auf einen bereits an ein Device ge-
  2445. *                                  sendeten IORequest.
  2446. *
  2447. * Ergebnis:     Error   --> (BYTE) Ist NULL, wenn alles in Ordnung, sonst eine
  2448. *                                  Fehlernummer des angesprochenen Devices
  2449. *                                  (s.a. Device-Includes).
  2450. *
  2451. * Bemerkung:    Mit einem »SendCMD()/WaitCMD()«-Paar erreichen Sie praktisch
  2452. *               das gleiche, wie mit einem Aufruf von »DoCMD()«, nur mit dem
  2453. *               Unterschied, daß Ihr Task bei letzteren in Wartestatus ver-
  2454. *               setzt wird, und Sie bei ersterer Methode während der anfallen-
  2455. *               den Wartezeit (z.B. wenn eine Disk geladen wird) anderen Auf-
  2456. *               gaben nachgehen können (z.B. Berechnungen etc.). Sollte der
  2457. *               IO-Vorgang bereits beendet sein, wenn Sie diese Funktion auf-
  2458. *               rufen, dann kehrt sie unverzüglich mit entsprechenden Ergebnis
  2459. *               zurück.
  2460. *
  2461. * Siehe auch:   »DoCMD()«, »SendCMD()«
  2462. *«««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««««*/
  2463.  
  2464.